Tworząc kod żródłowy, eksperymentując z nim, mało komu chce się tracić czas na pisanie komentarzy i opisywanie kodu – przeciez za chwilę danego fragmentu może wcale nie być .

Niestety, w moim przypadku, często kod, który początkowo był eksperymentalnym staje się kodem docelowym. W takim docelowym kodzie panuje w konsekwencji nieogarniony bałagan. Pomyślałem więc, że może warto starać się opisywać projekt już od samego początku, modyfikując przypisy wraz z rozwojem plików źródłowych.

W tym celu dobrze jest stosować samokomentujący się kod – ale o tym innym razem. W tym wpisie pokaże co powinno znajdować się w nagłówku pliku źródłowego.

Opis pliku posłuży nam w przyszłości, gdy wrócimy do niego po długiej przerwie i będziemy dokonywać modyfikacji. Przyda się także w sytuacji, gdy udostępnimy projekt innym – ułatwimy im pracę z naszym kodem.

Jakie informacje powinien zawierać nagłówek?

W nagłówku można umieścić wiele informacji mniej lub bardziej istotnych dla danego odbiorcy. Podzielmy je na trzy grupy:

• Podstawowe
  • Project – nazwa projektu z którego pochodzi plik. Pozycja przydatna, gdy plik stanowi tylko część wiekszego projektu.
  • Version – wersja pliku. Informacja na temat wersji pozwala zweryfikować aktualność pliku – szczególnie osobom trzecim.
  • Author – autor pliku.
  • Description – opis. Tutaj warto opisać jaką funkcję pełni kod zawarty w pliku np. że stanowi pętle główną lub zawiera funkcje odpowiedzialne za obsługę wyświetlacza LCD itp.
• Dodatkowe
  • License, Copyright, Dependencies – informacje o licencji i prawach autorskich oraz zależnościach (powiązaniach) względem innych plików (np. wymaga pliku z funkcjami obsługi SPI).
• Specyficzne
  • Hardware – na jakim sprzęcie działa oprogramowanie (np. na jakim mikrokontrolerze).
  • OS itp. – inne specyficzne informacje dla danego projektu.

Forma

Możliwych form opisania projektu jest tyle co programistów (a nawet więcej). Poniżej pokazane są dwa przykładowe opisy, które można wykorzystać jako szablon we własnym projekcie.

Niektóre środowiska programistyczne automatycznie dodają taki nagłówek, lub przechowują informacje o projekcje w osobnym pliku (również historię zmian).

Przykład 1 (forma zwięzła)

/*
Author: mj
Description: Software SPI library
Version: 0.11
Hardware: AVR family
 
Notes: initial version, todo: cleanup code, rebuild test function
*/

Przykład 2 (forma przejrzysta)

/****************************************************************************
 
 File			:	main.c
 Version		:	0.01 (2009.08.11)
 Project		:	RF12
 Author		:	mj
 
-----------------------------------------------------------------------------
 
 Copyright		:	(c) 2009 by mj
 License		:	GNU GPL v2
 
-----------------------------------------------------------------------------
 
 Hardware		:	ATMega88 + RFM12
 
-----------------------------------------------------------------------------
 
 Description		:	Hope RFM12 module test - TX part.
 
-----------------------------------------------------------------------------
 
 Changelog		:	0.01 - initial version
 
****************************************************************************/

Powyższe przykłady są w języku angielskim. Język angielski stanowi podstawę składni większości popularnych języków programowania, dlatego warto konsekwentnie stosować go także w opisie projektu (nawet jeśli późniejsze komentarze są w innym języku).

Podsumowanie

Powyżej zaprezentowane zostały przykładowe nagłówki plików źródłowych, zawierające opis zawartości danego pliku. Podkreślam, że są to tylko przykłady i informacje o pliku mogą wyglądać zupelnie inaczej. Niezależnie od tego, warto opisywać tworzony kod – wyrobić w sobie nawyk, który w przyszłości znacznie ułatwi nam pracę.

Oceń ten wpis:

(Nikt jeszcze nie ocenił tego wpisu)

 Loading ...

Wyświetleń: 3 701

Podobne artykuły

• Obecnie nie ma podobnych artykułów. Sprawdź za jakiś czas :-)