On Sun, Mar 8, 2009 at 7:06 AM, Allan McRae <firstname.lastname@example.org> wrote:
> if (you don't want to read a semi rant)
> * exit 0;
> I have noticed a number of useless comments in makepkg and have decided that
> they are worse than no comments. *Examples:
> 1) *This inspired the rant!
> * download_sources
> * # we can only check checksums if we have all files
> * check_checksums
> Huh, why are we not checking for all files then? *Because download_sources
> exits when it fails...
The problem with this comment is maybe more that it could be
misleading. It could let us think that check_checksums assumes that
all the files are here. But that is not the case.
But there is still one interesting information here, it's what you
said in your comment : "if download_sources return, it means all files
So the comment could be :
# we have all files now, so check their integrity
> 2) *and there are a lot of these:
> * # fix flyspray feature request #2978
> * # fix flyspray bug #5923
> * # Fixes FS#10039
> * # fix flyspray #6246
> * #fix flyspray feature request #5223
> * # fix flyspray bug #5973
> and I am guilty here... *but I was at the airport with no internet access so
> I had no idea if these are important. *And most of these appeared to be
> non-obscure features/fixes so did not need a comment justifying their
If one of these fixes is not totally obvious, I would say it would be
better having some comments explaining quickly what is done and why
rather than having a link to flyspray.
If it is obvious, I agree that no comment and no fs link is needed.
> 3) overly obvious comments
> * # do we have a changelog?
> * if [ -f "$startdir/ChangeLog" ]; then
> If you do not understand that test, then leave the code alone...
Now that's a typical example of useless comment, much more than the above
pacman-dev mailing list