[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