Do you know where your variables are? | |
PerlMonks |
comment on |
( [id://3333]=superdoc: print w/replies, xml ) | Need Help?? |
Personally, I try to use self explanatory names wherever possible, use my ($various, $param, $here) = @_; for positional arguments, and generally try to write the code in such a way that such information is contained in the code wherever possible. This also impacts the surrounding code - if your functions and methods are well named, the code using them will also be easier to read. My maxime is that if you feel the need to add a lot of comments, then something's fishy about your structuring and naming style. Between the public documentation and the code, not much room should be left for comments on the code. Write code with as few indentation levels as possible (but break this rule when it makes the code read more naturally), mostly using last and friends. Always name variables sensibly. Avoid having more than two or three subexpressions in a single condition. Do things Once And Only Once, so that you take up less screen space and end up with fewer but more expressive distinct things to understand. Capture regularities in code, irregularities in data. Do the tersest and simplest thing that can possibly work. These and more, similar ones are the things to strive for when writing code. Follow them well, and you will find that even scarcely commented code is comprehensible. However,you should meticulously document your data structures. The clarity of the code hinges on your understanding of the data it manipulates. That is something you should pay very close attention to. In essence, good programming skills means good data structure design skills. Show me your flowcharts and conceal your tables, and I shall continue to be mystified. Show me your tables, and I won't usually need your flowcharts; they'll be obvious. If the data structures are well designed, the code to manipulate them will suggest itself. If they are well documented, the code that manipulates them will suggest its intent with hardly any commentary. Makeshifts last the longest. In reply to Re: Documenting Methods/Subs
by Aristotle
|
|