On Sun, Mar 8, 2009 at 7:06 AM, Allan McRae <[email protected]> wrote: > Hi, > > 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 are here" So the comment could be : download_sources # we have all files now, so check their integrity check_checksums > 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 > inclusion. > 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 [email protected] http://www.archlinux.org/mailman/listinfo/pacman-dev
