Dokumentacja projektu w portfolio

Hej. Jestem na ostatnim etapie tworzenia projektu do portfolio. ~10 kilo kodu, w mojej ocenie dobrego kodu. Nie wiem jak na takie projekty patrzą rekruterzy, czy ktokolwiek kto to czyta i weryfikuje. Mimo, że komentarzy w kodzie praktycznie brak, nazwy metod i pól mówią same za siebie. Mam w głowie dwa pytania:

1. Czy powinienem przelecieć cały kod i nanieść komentarze? Jeśli tak, to jak szczegółowe?
2. Jak sporządzić dokumentację/readme dla czytającego?

Myślałem, żeby omówić lub rozrysować drzewko projektu i skupić się na najważniejszych klasach np. fasady. Dodatkowo opisałbym w jaki sposób potencjalnie rozbudowywać projekt.

1. zrób testy i javadoc to maks

i tak mała szansa że ktoś zajrzy w kod

Mimo, że komentarzy w kodzie praktycznie brak, nazwy metod i pól mówią same za siebie.

No i o to chodzi. Komentarze to słabość. Dobry kod to taki, w którym nie ma komentarzy, bo można z kodu się domyślić co kod robi. Nie zawsze da się zrealizować to zadanie w 100% i dlatego czasami trzeba nanieść komentarze.

Tak jak z książkami. Czasem tłumacze/redakcja daje gwiazdkę i na dole "przyp. tłum." albo "przyp. red.", ale nikt na siłę nie leci i nie dodaje tych przypisów (pomijając prace akademickie czy magisterskie, gdzie im więcej przypisuf tym bardziej ęteligętnie XD).

Pokaż kod.

Nikt nie będzie patrzył na ten kod chyba że wyraźnie w ogłoszeniu mówią że chcą zobaczyć kawalek twojego kodu, ale wtedy też popatrzą na jakieś 2 losowe klasy ;]

jesli masz doswiadczenie zawodowe i nie bylo nigdzie napisane abys przygotowal projekt to nikt tam nawet nie zagladnie. Beda sie ciebie dopytywac o projekty komercyjne.

Lectre napisał(a):

Jestem na ostatnim etapie tworzenia projektu do portfolio. (...) ~10 kilo kodu, w mojej ocenie dobrego kodu. (...)
70% czasu poprawiałem co tylko się dało, by nie było gdzie się przyczepić :P

Shalom napisał(a):

Nikt nie będzie patrzył na ten kod chyba że wyraźnie w ogłoszeniu mówią że chcą zobaczyć kawalek twojego kodu, ale wtedy też popatrzą na jakieś 2 losowe klasy ;]

Twój kod zostanie przeanalizowany - ale chyba tylko jak ten kod - to rozwiązanie zadania rekrutacyjnego.
<trocheHejtu>I nie pisze tutaj o jakimś śmiesznym codility (ale #magistry też muszę mieć jakieś szanse, bo przecież potrafią tylko rozwiązywać zadania o żabach albo klepać CRUD'y oparte o servlety)</trocheHejtu>

Moim zdaniem nie ma sensu nanosić komentarzy ani robić dokumentacji. Nie zgadzam się jednak z tym, że nikt do kodu nie zajrzy. Zależy od firmy. Jeśli nie składasz CV do korpo gdzie tygodniowo mielone jest kilka, kilkanaście aplikacji lub więcej, tylko do mniejszej firmy, to szanse na to że ktoś jednak kod przejrzy rosną. Z doświadczenia wiem że istnieje przynajmniej jedna firma, w której kod udostępniony przez kandydata jest analizowany. :) Oczywiście nie jest to jakaś dogłębna analiza, tylko raczej max. kilkunastominutowe pobieżne oglądanie. Jednak pozwala to wysnuć jakieś wnioski o kandydacie.