Wysyłam moją bibliotekę pierwszej klasy. Jakieś problemy, o których muszę wiedzieć?


12

Jestem programistą internetowym, który ma zamiar odblokować osiągnięcie „Pierwsza biblioteka opublikowana” w mojej karierze i pocę się pociskami (całą noc się stresowałem). Chciałbym wykorzystać doświadczenie społeczności, aby zobaczyć, czy ktoś ma jakieś sugestie lub rekomendacje, aby upewnić się, że pójdzie tak gładko, jak to możliwe. Czy są jakieś szczególne szczegóły lub problemy, o których muszę wiedzieć? Czy jest coś wyjątkowego w procesie kompilacji, który może mnie ugryźć?

Oto gdzie jestem:

  • Biblioteka jest testowana jednostkowo i ma około 97% pokrycia kodu
  • Interfejs API jest dobrze udokumentowany i utworzono dokumenty XML dotyczące obsługi Intellisense
  • Zapewniłem, że akcesoria klasy publicznej / prywatnej są dokładne i poprawne. To samo dotyczy wszystkich pobierających / ustawiających
  • Obsługa błędów nie jest tak pełna wdzięku, jak bym tego chciał, ale jestem przed terminem i zaakceptowałem, że jest to „tak dobre, jak to będzie”
  • Brak przyjaznego logowania. Debug.Writeline był szeroko stosowany ... Niedawno dowiedziałem się, że jest to odzwierciedlenie mojego braku doświadczenia :(

Wasze rady są bardzo mile widziane!

Biblioteka będzie używana do generowania raportów. Standardowy kapelusz - łączy się z bazą danych tylko do odczytu, wykonuje kalibracje, formatuje i wyprowadza dane do strumienia odpowiedzi.


Zostałem wykorzystany jako zasób poboczny, aby wypełnić jednego z programistów, którzy odeszli, a to zadanie zostało mi powierzone jako projekt „obetnij zęby”. Zostanie wydana biblioteka klas, z której będą mogli korzystać inni programiści w firmie podczas pisania kodu produkcyjnego.


2
Potrzebujesz szczegółowych informacji, jak to zrobić? Wydać na sprzedaż? Zwolnić otwarte oprogramowanie do udostępniania? Zwalniasz klienta z umowy, na której jesteś? Zwalniasz resztę swojej organizacji programistycznej w ramach projektu dla swojego pracodawcy w pełnym wymiarze godzin? Wydanie w wersji 1.0 nowego produktu do dostępności dla klienta dla swojego pracodawcy w pełnym wymiarze godzin?
Jimmy Hoffa

@JimmyHoffa: dodano odpowiedzi na pytania. Dzięki za poświęcony czas!
Pan JavaScript

1
Udawaj, że jesteś użytkownikiem biblioteki bez wiedzy o tym, jak ona działa. Użyj go, aby coś zbudować. Zmień / usuń / dodaj rzeczy w zależności od doświadczenia. Następnie przekaż go prawdziwym użytkownikom i uzyskaj ich opinię.
mike30

Może użyj Sandcastle lub innej biblioteki generującej dokumenty, aby mieć materiały referencyjne offline (ish)?
Jesse C. Slicer

7
Zrelaksować się. Posiadanie nawet jednego testu jednostkowego i jednego wiersza dokumentacji API już podnosi tę wersję ponad ~ 95% kodu „wydanego innym programistom w firmie do użycia”, z mojego doświadczenia.
Carson63000,

Odpowiedzi:


8

Zablokuj interfejs API

Sztuka skutecznego budowania API polega zarówno na zarządzaniu oczekiwaniami, jak i na strukturze.

Kiedy mówię API, odnoszę się konkretnie do nazw publicznych / wewnętrznych klas / metod i jaki jest ich poziom dostępu (tj. Prywatny / publiczny / wewnętrzny).

Jeśli obawiasz się, że kod może nie być w pełni gotowy do uruchomienia, zawsze możesz początkowo opublikować go w wersji beta.

Wydawnictwa:

  • Beta (tj. Wcześniejsza niż 1.0)

    • może zawierać wiele zmian w podziale API
    • może brakować zmian kompatybilności wstecznej między wersjami
    • może brakować połysku
  • Oficjalny (1.0+)

    • Interfejs API jest zablokowany do następnej wersji głównej
    • wszelkie wprowadzone zmiany powinny gwarantować kompatybilność wsteczną
  • Drobne (ex 1.1)

    • zawierają poprawki błędów i / lub implementacje funkcji
    • może uzupełniać zdefiniowany interfejs API, ale go nie usuwać

Jeśli uważasz, że interfejs API musi być zahartowany w bitwie, to wypuść go na jakiś czas w wersji beta. Oznacza to, że jest dostępny do użycia, ale nie powinien być wykorzystywany do produkcji i / lub kodu o znaczeniu krytycznym.

Wiele osób traktuje schematy wersji numerowanej jak pranie świń, ale kiedy są one skutecznie wykorzystywane, można je wykorzystać, aby zapewnić trochę miejsca na poruszanie się, dopóki struktura nie zostanie uporządkowana.

Twoje założenia dotyczące tego, w jaki sposób będzie on wykorzystywany, są błędne

Bez względu na to, jak dobrze coś jest zaprojektowane, ludzie znajdą sposób na znęcanie się lub alternatywne użycie.

Jednym ze sposobów na poradzenie sobie z tym jest zablokowanie jak największej liczby wdrożeń za pomocą akcesoriów (tj. Prywatnych / publicznych / wewnętrznych), ale żadna ilość projektu lub inżynierii nie da tyle wglądu, co udostępnienie kodu użytkownikom.

Naprawdę nie ma znaczenia, jak „idealny” Twoim zdaniem może stać się Twój kod, użytkownicy udowodnią, że tak nie jest.

Twierdziłbym, że jest to główny powód, dla którego zawsze lepiej jest użyć istniejącej bazy kodu niż wykonać pełne przepisywanie. W najlepszym razie całkowite przepisanie usunie wzdęcia, ale istnieje duże prawdopodobieństwo, że nowa baza kodów będzie zawierać tyle błędów (i być może więcej) niż oryginalna baza kodów.

W twoim przypadku zahartujesz się od zera, więc równie dobrze możesz zacząć.


Wygląda na to, że masz resztę swoich baz. Dokumentacja API jest niezbędna, a testy będą dobre dla zapewnienia stabilności, gdy zmiany zostaną wprowadzone w przyszłości.

Wdrożenie spójnego schematu rejestrowania będzie ważne przed wydaniem kodu do produkcji, ponieważ będzie potrzebny sposób globalnego włączenia / wyłączenia / filtrowania dzienników. BTW, w większości przypadków rejestrowanie naprawdę wymaga tylko importu biblioteki i zmiany wywołań wyjściowych z Debug.WriteLine () na coś takiego jak Logging.Debug (), Logging.Info (), Logging.Error (). Sam logger zapewnia jedynie standardową implementację konfiguracji, filtrowania i szerszy zakres schematów wyjściowych (pliki ex, konsola itp.).

Poza tym chciałbym wydobyć kod i zostać wykorzystany. Nawet jeśli tylko niewielka liczba użytkowników na początek.


1
+1 Re: logowanie - bardzo polecam TraceSource . Nie wprowadza żadnych zewnętrznych zależności, ponieważ jest częścią podstawowych bibliotek .NET i pozwala użytkownikom dołączać detektory i konfigurować śledzenie zarówno za pomocą kodu, jak i plików app.config.
Dan Lyons,

4

Są dwie rzeczy, które uważam za kluczowe do wydania oprogramowania:

  • Dowiedz się dokładnie, co wydałeś
  • Zarządzaj oczekiwaniami

Chcesz móc cofnąć się i naprawić błędy, które wydałeś i chcesz, aby ludzie zrozumieli, jaki problem rozwiąże Twój kod.

Wiedząc, co wydałeś

Upewnij się, że masz poprawną wersję i podpis (jeśli jest to odpowiednie). Użyj kontrolki źródła, aby oznaczyć \ oznaczyć kod związany z oficjalnie wydaną wersją. Pomoże Ci to łatwiej zidentyfikować błędy, ponieważ możesz wrócić do dokładnie wydanego kodu źródłowego. Pomoże to również w dalszym ciągu, gdy możesz mieć kilka różnych wydanych wersji.

Postaraj się, aby najnowsza wersja była łatwa do zdobycia i aktualizacji. To, czy jest to instalator, czy po prostu umieszczenie go we wspólnym udziale, zależy od tego, kto \ kiedy \ jak często będziesz wysyłał.

Upewnij się, że masz kogoś do sprawdzenia ostatecznej wersji, w tym dokumentacji. Bardzo łatwo jest się denerwować lub ekscytować wydaniem oprogramowania i przeoczyć coś.

Zarządzanie oczekiwaniami

Udokumentuj ograniczenia i uczyń je rozsądnie oczywistymi dla programistów. Dobrze, że je znalazłeś. Ludzie często lepiej rozumieją, jeśli znają ograniczenia związane z twoim oprogramowaniem, zwłaszcza jeśli masz plan, aby je naprawić.

Dokumentuj, w jaki sposób chcesz otrzymywać opinie, dobre lub złe. Ponieważ jest to projekt wewnętrzny, jeśli każdy ma dostęp do wspólnego systemu śledzenia błędów, poproś go o zgłoszenie błędów w odpowiednim projekcie.

W przyszłości unikaj zmiany interfejsu API, jeśli to możliwe, jest to jedyna rzecz, która może potencjalnie irytować klientów. Pamiętaj, że wyjątki są również częścią API, nawet jeśli w C # nie są częścią dokumentacji metody. To może być możliwe, aby poprawić wyjątki wyrzucane w późniejszym terminie, ale trzeba będzie rozmawiać z użytkownikami końcowymi i zobaczyć, jaki wpływ będzie to miało.


0

Mam listę kontrolną dla wdrożeń, które mogą okazać się przydatne. Zajmuję się tworzeniem pulpitu, ale niektóre z nich powinny zostać przetłumaczone. Oto niektóre z nich:

Generał:

  • Wstaw sprawdzanie wartości NULL dla parametrów funkcji, które nie powinny mieć wartości NULL. To pomaga mi wcześnie zawieść.
  • Usuń niepotrzebne komentarze i skomentowane pliki. Powodują one przyszłą pracę.
  • Wyszukaj komentarze „// TODO”. Czasami zostawiam notatki dla siebie. Czasami o nich zapominam.
  • Uruchom test mojego kodu, jeśli to możliwe, używając produkcyjnej bazy danych. Pomaga to zapewnić, że wszystkie zmiany w mojej bazie danych są wprowadzone na serwerze produkcyjnym.
  • Wprowadź obfite rejestrowanie. Zwłaszcza w przypadku pierwszego wdrożenia. W rzeczywistości zapisuję rejestrowanie na koniec, ponieważ w tym momencie mój kod zwykle jest trochę zżelowany. Nie chcesz być w sytuacji, w której masz awarię i mówisz sobie: „Gdybym tylko wiedział, jaka jest wartość X w tym czasie”. Staraj się planować z wyprzedzeniem.
  • Spróbuj zawrzeć wywołania biblioteczne innych firm w elewacjach. Ułatwia to zmianę bibliotek w przyszłości, a także zapewnia listę kontrolną wymaganą od biblioteki.

Specyficzne dla sieci:

  • Upewnij się, że wywołuję Dispose () na obiektach jednorazowych. Używam Code Analysis lub FxCop, aby znaleźć przypadki.
  • Upewnij się, że poprawnie odpinam wszystkie moduły obsługi zdarzeń. Zapobiega to wyciekom pamięci.
Korzystając z naszej strony potwierdzasz, że przeczytałeś(-aś) i rozumiesz nasze zasady używania plików cookie i zasady ochrony prywatności.
Licensed under cc by-sa 3.0 with attribution required.