in reply to My philosophy on coding (in Perl and other languages):

What do you mean by "document the hell out of your subroutines"?

Pick up The Pragmatic Programmer or Code Complete, and read what they have to say about comments. As long as you expect to have separate documents for the maintainer and the computer, you are doing something wrong. Document the interface, not the code. Make the code its own comment. (Good variable and function names really helps. So do well-written messages in your error checks.)

My second point is references. Don't use references because they are cool - OK I can buy that. But don't go out of your way to avoid nested data structures either. (Which happen to use references.) Gratuitous abuse of references is bad, but so is the gratuitous abuse of virtually any other feature. Why single out references?

Other than those two nits I think you are spot on.

A final point that is too often forgotten. There is nothing wrong with not knowing something. Programming is a field that is constantly changing and you will constantly be dealing with things you don't know. So if you have any questions at all, check the documentation and if you cannot figure it out, start asking questions.

Not knowing is expected. But if you are not learning then you have a problem.

  • Comment on RE: My philosophy on coding (in Perl and other languages):

Replies are listed 'Best First'.
Re: RE: My philosophy on coding (in Perl and other languages):
by ichimunki (Priest) on Dec 26, 2000 at 22:11 UTC
    I know this is a very late response to a now-old node, but I want to add that commenting code using #comments is less useful than documenting code using =pod / =cut slices. I just picked up the habit of putting all major information into POD and I'm loving it.

    This way my subs (or packages) can sit in fully-documented separate files and if I need to know something I don't have to sort through the code to learn find it, perldoc package_name.pl gets me to the information I need very quickly (this is basically an echo of Tilly's comment about documenting the interface). Storing the libraries as libraries (instead of putting all the code in a single file) during development means that the POD in the packages does not interfere with the POD for the main script-- this also means that I can share my package with others easily, since the docs are already written. Sometimes # is good for short notes, but for longer notes, you can always use POD tag like =note to make notes that don't show up in the normal course of POD parsing.
[reply]
[d/l]
RE: RE: My philosophy on coding (in Perl and other languages):
by mrmick (Curate) on Aug 15, 2000 at 21:05 UTC
    I actually just started reading the Pragmatic Programmer yesterday (got it from Fatbrain - and that wasn't a plug).

    My only issue is with your statement: "Make the code its own comment. "
    Since not everyone will use meaningful names when writing their code (I'm certain you have seen it too), I tend to think that comments are important. Now, I didn't mean comment every line - or even every 3rd line. I meant that (and I should probably have said) there should be a decent description for the subroutine and what(sometimes how) it does. After all, why do we have the '#' if we shouldn't use it?

    Thanks for the feedback. It's good to know that people are actually reading what I post and taking the time to comment on it. :-)

    Mick
[reply]
      philosiphising? does anyone know how to spell that word?

      anyway... my first programming teacher taught me that when you're commenting subroutines (or functions or methods) its usually a good idea to put in a 'precondition:' statement and a 'postcondition:' statement. in other words, tell the reader what the subroutine expects to recieve as arguments (including implicit error-checking perhaps) and what the subroutine will spit out as a return value.

      jeff
[reply]
      Well put it this way. If humans read a different document from the computer, you have a problem. The fact that there are programmers who do not understand how to code well is their problem. If you rely on such programmers and have put no thought into communicating your requirement that the code have decent quality, then their problem has become yours.

      Bad programmers are a hazard to your code-base. So give them feedback and review. Doing that up front saves energy in the end over letting it pass and cleaning up after. A stitch in time and all that.

      BTW I do comment most subroutines. Input arguments, brief description, and return. Often only the ones that are meant to be used outside the module though...

[reply]

In Section Meditations