Wednesday, April 19, 2006

bare minimum required comments for your projects

commenting is one of the things that programmers/developers really suck at

but please, do your self a favor

at the VERY LEAST, put comments at the top of the main source file; for example whenever I start a new project I always put something like:

Program: Program Name
Written by: Eber Irigoyen
on: 04/19/2006
Uses (third party components):
- Indy 9.0.14
- XceedZip 4.5.77.0
- MDAC 2.7
Compiled with: Delphi 7

Description:
- blablabla
- more bla
- etc...

include any history updates here...

is just a few lines and it tells me quite a lot, how many times have you spent hours just because you don't know what version of the X components some co-worker used?

adding these headers will take you only a minute or two, and it can save countless hours in the future

the next thing is whenever you make changes to your project, at least include a description at the top of the main file, along with the version number, your name and date when the update was done

simple things like this are part of being a better developer

note: Updated the article to clarify some points just like Ayende mentions in the comments, another thing is that you should include the 3rd party components in the source repository;
the bare minimum comments in the source and the components in the source repository are real life savers!

5 comments:

Ayende Rahien said...

I agree that this stuff is important, but I don't think that is should be in each and every file.

It should be in the source repository, which should include all the 3rd party components, detailed history of all the changes, as well as a document (I like to use TiddlyWiki or Word) that gives high level overview, etc.

BlackTigerX said...

you're right, I didn't clarify that, I usually put it in the main file and on the source repository

Renoreins said...

Me da una weba tan inmensa ponerme a hacer eso, además que generalmente se me olvida hacerlo.

'Ora si lo haré con el sistemita que voy terminando, Saludos!

BlackTigerX said...

pues es que acuerdate que el webon trabaja doble, si no le pones ahorita un minuto para incluir eso, despues vas a pasarte algunas horas buscando que version exactamente usaste, que cual componente hay que registrar... y si trabajas en un equipo de programadores, y todos hacen lo mismo, todo fluye mucho mejor

Anonymous said...

Honestly, comments are only needed when you want to apologize for your bad code.

If anyone wants to see history of the code, you could check the source control logs.

Or the release notes.