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!
Wednesday, April 19, 2006
Subscribe to:
Post Comments (Atom)
5 comments:
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.
you're right, I didn't clarify that, I usually put it in the main file and on the source repository
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!
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
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.
Post a Comment