[thelist] Basic Documentation Questions
rudy
r937 at interlog.com
Fri Feb 8 11:18:01 CST 2002
> /* Make all our keys lowercase for consistency */
> $new_data = $this->keystolower($data);
> /* Loop through each transaction */
> foreach ( $new_data as $key => $transaction )
>
> In the style above, you can pretty much grasp what we are doing at
> each stage. Commenting like this helps out tremendously in the long run.
hi jason
great advice
however, those two examples are rather poor (i realize you just used them
to illustrate inline comments)
i don't know what language that was, but assuming i knew it well enough to
try to maintain it, i would find those comments superfluous
working code is not the place to be telling me that "keystolower()"
translates keys to lower case, or that "foreach" performs a loop
inline comments have to be appropriate
like peter said, they should "explain what a piece of code does" and
"explain any strange quirks of the code"
my goal is always to write code that is self-explanatory and has no quirks
;o)
> ... create a documentation paper or the like. This way, someone
> can use your code without having to go through all the code.
excellent point
rudy
More information about the thelist
mailing list