Dobra nazwa, czy zła – na przykładzie Apache POI

Apache POI to jedna z bibliotek, z którym dość często pracuję. Głównie korzystam z jej możliwość w kontekście obsługi plików Microsoft Excel, które w branży finansowej i księgowej są bardzo potrzebne. Jak każda biblioteka ma swoje mankamenty. Ale dzisiaj… dzisiaj skupimy się na ciekawym podejściu do nazywania komponentów.

Jak nazwać klasę?

Czy klasy i interfejsy powinny mieć nazwy oddające ich zastosowanie?

Zdecydowanie tak.

Czy mogą przy okazji nieść nieco głębsze przesłanie?

Hm… zobaczmy. Twórcy Apache POI zastosowali tutaj niekonwencjonalne podejście do wyboru nazw. Poszczególnych komponenty biblioteki mają w swoich nazwach prefiksy o wdzięcznych angielskich rozwinięciach:

• POIFS (ang. Poor Obfuscation Implementation File System) – komponenty podstawowe do obsługi dokumentów OLE 2.
• HSSF (ang. Horrible SpreadSheet Format) – wszystko do obsługi starego formatu XLS.
• XSSF (ang. XML SpreadSheet Format) – umożliwia pracę z formatem XLSX, czyli Excel zgodnie Office Open XML.
• HPSF (ang. Horrible Property Set Format) – czyli format zapisu właściwości dokumentu.
• HWPF (ang. Horrible Word Processor Format) – stary format DOC.
• XWPF (ang. XML Word Processor Format) – obsługa DOCX, czyli Word zgodnie z Office Open XML.
• HSLF (ang. Horrible Slide Layout Format) – obsługa starego formatu PPT, PowerPoint.
• HDGF (ang. Horrible DiaGram Format) – obsługa ulubionego formatu wielu architektów, czyli MS Visio.
• HPBF (ang. Horrible PuBlisher Format) – dla Microsoft Publisher – jeśli ktoś tego jeszcze używa.
• HSMF (ang. Horrible Stupid Mail Format) – dla odważnie stąpających po załącznikach programu Microsoft Outlook MSG. Jeśli musiałeś kiedyś skorzystać z tej grupy komponentów, to z pewnością wiesz, że odwaga była niezbędna do wykonania tego zadania.
• DDF (ang. Dreadful Drawing Format) – Microsoft Office Drawing, pomińmy milczeniem.

Sądzę, że w tym miejscu zgodzisz się ze mną. Przyznasz, że twórcy Apache POI podeszli do nazewnictwa w sposób nieszablonowy.

Oczywiście poza klasami takimi jak HSSFWorkbook, XSSFWorkbook, XSSFCell, XSSFCellStyle, XSSFConnector, XSSFDataFormat, XSSFVMLDrawing, Apache POI stosuje dla nich abstrakcje. Czyli w dobrze napisanym kodzie będziesz raczej używać referencji do interfejsu Workbook niż bezpośrednio do XSSFWorkbook.

Filtr Clean Code

Ok. Skoro znamy już konwencje nazewnicze to zastanówmy się, jak one wpisują się w nurt Clean Code. Zadajmy zatem kilka pytań na podstawie naszej wiedzy zdobytej z tej książki.

1. Czy nazwy klas przedstawiają intencję?
   TAK, choć ich prefiksy składają się z akronimów, to zdecydowanie ich konwencja nazewnicza zapada w pamięć i bez problemu szybko pamiętamy skąd się bierze.
2. Czy nazwy nie prowadzą do dezinformacji?
   TAK, te nazwy jasno określają z czym pracujemy. Jeśli korzystamy z implementacji XSSFWorkbook to wiemy, że programujemy pliki MS Excel w formacie XLSX.
3. Czy są to nazwy wyraźnie różne?
   NIE. Na pierwszy rzut oka wiadać, że w kodzie ciężko będzie odróżnić HSSFWorkbook od XSSFWorkbook.
4. Czy łatwo je wymówić?
   NIE. Chyba, że znamy rozwinięcie akronimów. Ale generalnie nie bardzo.
5. Czy łatwo je wyszukiwać?
   TAK. Na pierwszy rzut oka wyglądają podobnie. Ale z punktu widzenia przetwarzania maszynowego jest to różnica ogromna. Także dla naszego oprogramowania wyszukiwanie klas na podstawie ich nazw nie stanowi problemu.
6. Czy unikają kodowania?
   NIE, bo mamy akronimy.
7. Czy unikają odwzorowania mentalnego?
   TAK. Choć należy wyjaśnić, że w Clean Code, ten punkt skupia się na jednoliterowych nazwach.
8. Czy utrzymują konwencję rzeczowników dla klas?
   TAK. Choć z prefiksami.
9. Czy …?

Ile pytań wystarczy, żeby stwierdzić, czy nazwa jest dobra?

No właśnie. jak długo trzeba się zastanawiać nad nazwami pisząc kod? Ile pytań trzeba zadać?

Na podstawie książki Clean Code moglibyśmy zadać jeszcze co najmniej kilkadziesiąt pytań. W tym o to, czy nazwy w Apache POI nie są prześmiewcze, czy też, czy stosują język dziedziny rozwiązania.

Ale, czy tych pytań trzeba zadawać aż tyle? A, co gdy nazwa i tak nie wyłania się nam przed oczami przez dłuższy czas?

Jestem bardzo ciekawy, czy Twoim zdaniem takie podejście do nazewnictwa klas jest dobre, czy nie. Czy Twoim zdaniem Apache POI robi to dobrze?

Jak radzisz sobie, gdy na pierwszy rzut oka nie wiesz, jak nazwać daną klasę, czy metodę? Napisz w komentarzu 👐