I don't do this in my code as I'm more of a "code should be self-documenting, if it's not you've got a problem" person. Having said that, I do add comments to code inside subroutines to explain why things were done a certain why or to explain something complicated.#---------------- # doStuff(@args) # # This method does this and that and something else. # Returns some foo data structure. # Blah, blah, blah # Mumble, mumble #---------------- sub doStuff {
We just had a new tester start here and she was quite surprised that none of the Perl code had commented subroutines. All Perl code at her previous job had commented subroutines.
I didn't think anything more of it until I was taking a peek at Andy Wardley's rather spiffy XML::Schema this morning. That code has commented subroutines all over the place. I also notice this when downloading modules from the CPAN, some authors do comment their subroutines, others don't.
What's your take on it? Just personal preference or...
-- vek --
|
---|
Replies are listed 'Best First'. | ||
---|---|---|
Re: Documenting Methods/Subs
by Abigail-II (Bishop) on Jan 10, 2003 at 16:16 UTC | ||
It's not a black & white thing. I think that both those that document all subs and that document none are wrong. Good programmers know which subs to document and which subs can be left undocumented. ;-) Abigail | [reply] [d/l] | |
by Rex(Wrecks) (Curate) on Jan 10, 2003 at 18:42 UTC | ||
| [reply] | |
by autarch (Hermit) on Jan 11, 2003 at 05:04 UTC | ||
This is actually a good reason to use a module like Params::Validate, it helps provide documentation for a subroutine/method. For example: sub do_the_thing { my %p = validate( @_, { foo => { isa => 'Foo::Big' }, size => { type => SCALAR, default => 10 }, ... } ); ... } This way all the possible named arguments are documented, as well as their types/classes, defaults, etc. Along with good names, this really does completely document what parameters are accepted, _and_ as a bonus does actual validation on them. | [reply] | |
by pdcawley (Hermit) on Jan 12, 2003 at 16:45 UTC | ||
and similar tricks. If you're enforcing the object type you have to draft in Test::MockObject, which is great, but is also substantially more complex. | [reply] [d/l] | |
by adrianh (Chancellor) on Jan 12, 2003 at 23:07 UTC | ||
by pdcawley (Hermit) on Jan 13, 2003 at 07:14 UTC | ||
| ||
by autarch (Hermit) on Jan 16, 2003 at 03:20 UTC | ||
by pdcawley (Hermit) on Jan 16, 2003 at 08:16 UTC | ||
| ||
Re: Documenting Methods/Subs
by dragonchild (Archbishop) on Jan 10, 2003 at 16:35 UTC | ||
There's one file I'm working on right now that has every single function extensively documented with POD. I hate it, cause it gets in my way of seeing the whole code. But, when I first started working on it, it gave me a smidge of insight into what the author was thinking. (Granted, it's only a smidge cause the author sits about 50 feet from me, but it would've been a heck of a lot more if the author wasn't around to ask questions of.) I guess that if the person after you can ask you questions, don't comment it. If the person after will not be able to ask you questions, comment evey single assumption you make. YMMV. ------ Don't go borrowing trouble. For programmers, this means Worry only about what you need to implement. | [reply] | |
by seattlejohn (Deacon) on Jan 10, 2003 at 21:44 UTC | ||
I have to disagree. What if you leave the company? What if you get run over by a bus? What if you decide to go on vacation (heaven forbid!) and trek around the Himalaya for two weeks? Even if none of that happens, what happens when the code ships and gets forgotten, then someone decides to dust it off three years later? It's ancient history; will you really remember what you were thinking when you wrote it? I suppose it's possible to go overboard with documentation, but I guess I find it much easier to ignore something that is there than to fill in something that isn't. I rarely trust myself to be able to remember my own thought process a couple of years down the road, let alone reconstruct somebody else's. $perlmonks{seattlejohn} = 'John Clyman'; | [reply] | |
by dragonchild (Archbishop) on Jan 13, 2003 at 14:55 UTC | ||
Maybe my tongue was a little too far in my cheek. *winces* I firmly hold that the "Bus Number" of any group should never be 1. (And, if anyone can come up with a link that doesn't involve TWiki re: Bus numbers, that would be great!) ------ Don't go borrowing trouble. For programmers, this means Worry only about what you need to implement. | [reply] | |
Re: Documenting Methods/Subs
by Tanalis (Curate) on Jan 10, 2003 at 16:21 UTC | ||
I'm in the habit in the shop I work at of not commenting subs, unless they're very long and it's not obvious from the name or the routine itself what they're doing. Having said that, though, at my Uni it's expected that all subs are commented in depth, and I therefore do commment them there. It's normally a fairly safe assumption (in my mind) that someone working at the same place you do, with a grasp of what's going on with the system and what the script as a whole should do can figure out what a specific sub is doing (especially if it's well-named). I guess it depends on the people you work for (or are coding for, in the case of Uni) too .. and on their coding standards (or lack of) .. how much of a personal choice you get then is very much controlled by that. Just a few quick thoughts .. | [reply] | |
by krujos (Curate) on Jan 10, 2003 at 17:31 UTC | ||
Sorry one of my pet peeves is not commenting code other people will be using. Josh | [reply] | |
Re: Documenting Methods/Subs
by PodMaster (Abbot) on Jan 10, 2003 at 17:12 UTC | ||
how else would know what your API consists of? (it shouldn't be magic). Comments are not documentation -- or comments are documentation for the developers of the API. The users of the API should refer to the user documentation (the pod). Comments needn't truly be comments (=for comment ...=begin comment ...) I heartily disagree Abigail's comment that people who document every sub are wrong. There is no such thing as too much documentation, no matter how redundant it may be. Lack of documentation is almost always wrong (programmers should not resort to sourcediving to learn function names).
| [reply] [d/l] | |
by Tanalis (Curate) on Jan 10, 2003 at 17:33 UTC | ||
It can get to the extreme, very easily. Consider a simple sub to commify a number, called commify_number. There's no need for this to have a description of what it does - it's obvious. Large blocks of comments (or comments documenting most of the lines of code within the sub) for something like this are going to obscure what should be a relatively simple thing. My thoughts: if code is getting lost in a sea of comments, there's too many comments. Redundancy is largely irrelevant if the comments themselves are stopping you seeing what's going on. While I agree that a lack of docs is bad, it's very important to get some sort of balance between code usability (in a maintenence sense) and understanding, at least in my mind. -- Foxcub | [reply] [d/l] | |
by ihb (Deacon) on Jan 10, 2003 at 21:13 UTC | ||
When speaking of documentation, I mean things that document the particular module, philosophy, code snippet, or whatever the documentation is related to. If someone starts documenting how pack() works in the middle of the code or API then he's just lost track of what he's doing. However, there seem to be couple of misunderstandings here between fellow monks. Some speak of documentation, some speak of commentation, and some speak of commentation as documentation. Naturally, disagreements will arise. I usually wouldn't refer to comments as documentation. If someone says "look in the documentation" I certainly don't look for comments. I say that there can be too many comments, but too much documentation has never hurt me--as long as it has a sensible structure. If you end up with a long documentation with lots of examples and explanations in it you'd perhaps should start thinking about writing a separate tutorial or extract the examples to an own section. Has anyone ever complained about too many examples? For modules this means that you first document the most important things so people quickly can use your module. But towards the end of the documentation you very well can put a more detailed explanation and give examples to illustrate special features, nifty uses, or gotchas. If it's a "funky" module, i.e. it does something technically advanced with Perl itself (constant.pm to take a well-known module) it can be interesting with a little explanation or forward to documents explaining how the module achieves what it does so the reader gets a chance to learn and understand rather than being a simple user. This certainly can help the module author with finding bugs or even receiving patches. It also feeds for further development and other related and interesting ideas. So no, I wouldn't say that there can be too much documentation. (Remember that I don't count a pack() tutorial in the middle of code as documentation.) Just my thoughts, ihb | [reply] [d/l] [select] | |
by vek (Prior) on Jan 10, 2003 at 17:49 UTC | ||
I agree, and that is what POD is for. Remember that a lot of programs/modules have POD at the very end of the code (I've seen my fair share from the CPAN). As a programmer who wishes to learn the API I can do a quick perldoc foo and (hopefully) get everthing I need. I was referring to code where every method is documented by the type of comments I showed in my root node, including those private or debug methods of a class which won't be in the POD. -- vek -- | [reply] [d/l] | |
by autarch (Hermit) on Jan 11, 2003 at 05:16 UTC | ||
I heartily disagree Abigail's comment that people who document every sub are wrong. There is no such thing as too much documentation, no matter how redundant it may be. Abigail's a pretty smart person, and I think the slip from "comment" to "document" was unintentional. Yes, you should always document your whole public API. Otherwise it's not really public, is it? But don't waste my limited screen real estate on crap like this: # # Class->foo() - returns the value of foo for the object # sub foo { $_[0]->{foo} }Another commenting pet peeve: # if $x is bigger than 10 if ( $x > 10 ) { # set $x to $y modulus 50 $x = $y % 50; } # otherwise, if $y is not equal to 50 elsif ( $y != 50 ) { ... }Argh! I hate that so incredibly much. Comments that simply tell me _what_ the code is doing are absolutely, utterly useless. Always assume that the next person does understand programming logic, assume that they understand Perl, etc. Don't assume they know why something is the way it is, however. In the above code, I want to know why it's important to set $x to the $y modulus 50 only when $x is greater than 10. There are a few exceptions to the "no walk-through comments" rule. Very complicated algorithms may deserve very careful step by step comments. This can help you as you code, in making sure that you're actually following the algorithm, and it helps future readers. And if you deliberately write less-than-clear code, for example as an optimization (after benchmarking and profiling, please), then it may be worthwhile to comment the what of the code. But a good rule to follow is that if you think the what of the code is too hard to follow without comments, then you need to rewrite the code in a clearer manner. | [reply] | |
by Anonymous Monk on Jan 10, 2003 at 17:36 UTC | ||
There is no such thing as too much documentation, no matter how redundant it may be. Whew! Obviously you haven't seen the code I have.
Get the point? This completely distracts from the code and takes way more time on the part of the programmer. As for subs, I say one comment directly above them. Anymore and the sub is too long and should be broken into multiple subs. | [reply] [d/l] | |
by adrianh (Chancellor) on Jan 12, 2003 at 11:56 UTC | ||
There is no such thing as too much documentation, no matter how redundant it may be. Lack of documentation is almost always wrong (programmers should not resort to sourcediving to learn function names). Lack of needed documentation is always wrong - however over documentation, in my experience, can cause problems. For example: Personally, I tend to go for development environment with common code ownership and require unit tests for everything. I find this removes most of the need for comments and heavy API documentation during development. If the team discovers a need for documentation during development then we do it. If the team is not in-house then we will also have appropriate levels of design & implementation documentation as a deliverable (and we'll do it properly too :-) This has worked well for me with smallish projects (about a dozen coders max). | [reply] | |
by pdcawley (Hermit) on Jan 13, 2003 at 12:10 UTC | ||
All methods must be documentedRound objects! And so do I. Whilst I take your point that it's generally a good idea to document the methods that make up your public API, those methods will not be the same as the full set of methods to which an object responds. Anyone who works with your code needs to see documentation covering how you expect the code to be used (though I'm as guilty as the next man of failing to do this on one of the major projects I'm working on, partly because the API is still in flux). Anyone who works on your code should be using the source like God intended. And if you're not competent to write clear code then what on earth makes you think you're competent to write clear comments in a far more ambiguous language? | [reply] | |
by hardburn (Abbot) on Jan 13, 2003 at 16:45 UTC | ||
There is no such thing as too much documentation, no matter how redundant it may be. Yes there is. I'm working on replacing some programs right now that stop every 5 lines or so with 20 lines of comments. Just document the subs if it's not obvious from their names, then document anything you do that's clever but obscure. Anything more gets in the way of following the code, which is The Ultimate Documentation. | [reply] | |
Re: Documenting Methods/Subs
by jplindstrom (Monsignor) on Jan 10, 2003 at 18:41 UTC | ||
If it's not (e.g. a hairy regexp, or an effective but maybe-too-advanced-for-your-colleagues Perl idiom), a comment is useful. Or, if the code is too opaque, a comment can provide guide to what happens. But there are other cases. Why you do things are sometimes not obvious. Or it may be obvious to you, but it won't be to the maintenance programmer (that's you, in six months). But why is different from what. Code the what and comment the why. Some things are by definition not obvious. The interface (what you have in your example) should be explicitly documented for two reasons; it defines what the method/function actually does, and; before using a method you shouldn't have to spend time to understand how the code works, only what it does. And with a weakly typed language like Perl, it may not even be possible to deduce what kind of object to pass a method just by reading the code. The following example is from a program for replicating subsets of a Wiki to other Wikis.
The POD defines what the method does, and what it returns. If it was possible for it to die, that would be mentioned. The comment explains in user-level terms what the hash ref indicates. From the same program: The POD says what the method expects as input, what it does, and what it returns. The comment explains why duplicate names are ignored--there are none. I find it very useful to write the interface before coding the method. Yes, I know pretty well what I intend to accomplish when I start out, but writing the POD first gives me ten more seconds thinking about the problem, including the important things like what goes in and out, what boundary conditions there are, and how to handle errors. I wish to think that this improves the quality of the code.
Documenting the interface using POD instead of Perl comments makes is easy to extract the class definition programmatically, e.g. using (warning, shameless plug ahead) Perl Oasis: /J | [reply] [d/l] [select] | |
Re: Documenting Methods/Subs
by krujos (Curate) on Jan 10, 2003 at 17:21 UTC | ||
Commenting subs/methods are the something I feel that everyone should do. Those comments save me tons of time every day. Commenting in the code is nice as well (an I am not implying that one should be done in favor of the other, do both), but if I just want to use a sub that someone else has written I don’t want to have read the code to discover what it does (some time the function name is just not enough) and what I need to pass to it / what it will give back to me. This is what comments at the beginning of subs are for. From an ease of use standpoint, I don’t have to guess at what the sub does and I don’t have to care about how it does it, I only have to know what to give it in order to use it. This encourages code reuse because it makes the function easy to use. Comments in the code don’t really provide this abstraction for the programmer who has to come along and use these functions. Another point about inline comments is that they don’t really provide a general overview of what the function is doing. Inline comments are more often to document how something is done and explain trickery for certain lines / small blocks of code, not give an overview of the whole function. With a header comment you are forced (well sort of anyway) to do that. A general synopsis of a sub, its parameters and its return values is invaluable, epically in a large program that more than one person works on. Think how frustrating it would be to run into subs doing shifts all over the place to get parameters and such. One header comment about the required parameters and everyone else who uses the code is spared that work. All that said there are thousands of trivial subs that do exactly what the function name describes and are all of about five lines long etc… These proably do not need super indepth comments, but I still think it’s a good idea to comment these as well. Small subs are obviously less likely to confuse people (most of the time) than a huge, possibly epic sub. Josh UPDATE: After lauging my arse off at the AM reply I have decided to make it a little more readable My $.02 | [reply] [d/l] | |
by Anonymous Monk on Jan 10, 2003 at 17:38 UTC | ||
On the topic of clarifying things, breaking text with paragraph tags helps too ;-) | [reply] | |
Re: Documenting Methods/Subs
by Ctrl-z (Friar) on Jan 10, 2003 at 17:58 UTC | ||
| [reply] [d/l] | |
Re: Documenting Methods/Subs
by hardburn (Abbot) on Jan 10, 2003 at 17:29 UTC | ||
There are basically two cases I work with for subroutines: For the first, I always document everything with POD, except for private data. I think that someone using an object should never have to look at the actual source code, so it has to be documented, no matter how trivial. Subroutines in a program are different. If someone wants to use those, they have to be digging through the source anyway. Most of the programs I write are CGIs, and go through a simple set of subroutines almost every time (set parameters, validate parameters, read or write a database, print the results or an error message). The subroutines that do this job are given obvious names (set_params, validate, read_db/write_db, print_results). It seems silly to document these with a subroutine header. However, a CGI that needs something beyond this will have its additional subroutines documented. | [reply] | |
Re: Documenting Methods/Subs
by Aristotle (Chancellor) on Jan 12, 2003 at 18:29 UTC | ||
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. | [reply] [d/l] | |
by castaway (Parson) on Jan 13, 2003 at 10:33 UTC | ||
After all, if someone comes with code like this: When what they meant was: Then a usual response would be 'go away and write it so you understand it yourself in a years time, and then ask me again when it doesn't work'.
I agree completely about the data structures, the more so in perl where you can make hashes of arrays of hashes etc. I have some lovely ones which I wouldn't understand myself any more without the comments. | [reply] [d/l] [select] | |
by Wysardry (Pilgrim) on Jan 19, 2003 at 15:07 UTC | ||
I consider using descriptive variable and subroutine names to be a form of commenting/documentation. If you want your code to be easily understood by yourself and others, you do so. If you're trying to hide what you're doing, you don't. | [reply] | |
Re: Documenting Methods/Subs
by jaa (Friar) on Jan 11, 2003 at 14:59 UTC | ||
My favourite 'Comment the d*mn code' experience happened a few years ago - a frustrated workmate swore loudly and vociferously complained that so-and-so never commented his code and that he was fed up with trying to figure out what it was meant to do! I walked over to look at the code over his shoulder, just as so-and-so sauntered across and said… 'Hit Page Down' There were about three screens of comment explaining what was going on, why, and what was going to come back - pretty clear and detailed. The angry chap harrumphed, and proceeded to read (slowly…) through the code, highlighting each line as he read down, to make it easier to see (he was a long tooth contractor…). 'Well - ok! Sorry' he said when he reached the bottom. He then pressed the Enter key, replacing all those lovely comments with a blank line, and blithely proceeded to make his code modifications… We had finally figured out the answer to that song - 'Where have all the Comments Gone?' | [reply] | |
Re: Documenting Methods/Subs
by Wysardry (Pilgrim) on Jan 11, 2003 at 01:15 UTC | ||
Initially my answer was going to be "It depends on the size and complexity of the code" but then I stopped and thought for a moment. If a program contains subroutines, then it is a fairly safe bet that it is big or complex enough to require comments. After all, very few people use a subroutine in a 3 line program. ;) If it doesn't all fit on my screen without scrolling, then adding comments provides visible breaks in the code making it easier to find a specific section. So basically I add at least one comment to each subroutine (stating what it does on a single line) to make it easier to spot if and when the program gets larger. If I used some really hairy code - or something just plain weird - I'll add more detail, though not to extremes. I find it makes life easier that way - especially if I have to edit the code several months later or decide to reuse that subroutine elsewhere. | [reply] | |
Re: Documenting Methods/Subs
by Beatnik (Parson) on Jan 10, 2003 at 22:02 UTC | ||
Greetz Beatnik ... Quidquid perl dictum sit, altum viditur. | [reply] | |
by adrianh (Chancellor) on Jan 12, 2003 at 10:56 UTC | ||
You might be interested in this node, where I discuss some tests I wrote that do exactly that :-) | [reply] | |
Re: Documenting Methods/Subs
by Anonymous Monk on Jan 11, 2003 at 17:55 UTC | ||
We are looking for another Perl developer and are issuing a code test, if there aren't any comments in the code we 1: ask why and 2: put the resume on the bottom of the pile. The primary reason is that a job interview (and the code that goes with it) should be the _best_ that you can do. I'll probably be the one tracking down your bug at midnight and uncommented code makes me very unhappy.. (of course the 'you' in the above is not being directed to anyone specific).. | [reply] | |
by adrianh (Chancellor) on Jan 12, 2003 at 11:14 UTC | ||
Just because someone _thinks_ that their code is self commenting doesn't mean that they are correct. Just because somebody _thinks_ that their comment explains the code doesn't mean they are correct :-) Bad comments are just as evil as bad code. In fact they are worse, since you then have the problem of what is correct - the code or the comment. I'm not anti-comments - but they do have problems of their own which are often unacknowledged. Over the years I have found self-documenting code (tests, assertions, etc.) to be of more use in many, if not most, instances. I would also ask the coder why they didn't add comments - but I would see if they had sensible answers before consigning the resume to the bottom of the pile :-) | [reply] | |
by vek (Prior) on Jan 12, 2003 at 17:50 UTC | ||
-- vek -- | [reply] | |
Re: Documenting Methods/Subs
by BrentDax (Hermit) on Jan 10, 2003 at 20:37 UTC | ||
=cut | [reply] | |
Re: Documenting Methods/Subs
by castaway (Parson) on Jan 12, 2003 at 18:21 UTC | ||
In code I write for myself (primarily), I usually do something like: One or two lines is usually enough, the actual code only has comments in parts where I feel they are necessary to explain what it's doing.
I keep meaning to learn POD and add that, but it won't be as a replacement for comments, just to provide an overview how to use the modules without having to look at the code. | [reply] [d/l] | |
Re: Documenting Methods/Subs
by adrianh (Chancellor) on Jan 12, 2003 at 01:51 UTC | ||
Personally I comment when I think it needs a comment :-) My commenting style has gone from none (long, long ago when I was young and innocent), to far too much (after the first few times I had to maintain somebody else's code :-), to what is hopefully a happy medium. I've noticed in recent years that things I would have previously elucidated with a comment I now explain in other ways. For example: These have an advantage over textual comments because (apart from naming) they cannot get out of sync with the code base. | [reply] | |
Re: Documenting Methods/Subs
by jynx (Priest) on Jan 13, 2003 at 20:15 UTC | ||
TMTOWTDI, If i'm going to comment my code (which i only do for something which others will have to see and/or maintain) than i use the following setup which i have derived from my coding experiences: The notes area will explain any code that isn't self-documenting before one gets to the code. The "receives" and "returns" sections detail what will be set up before and after the function runs (pre/post-conditions). However, due to my idiosyncracies, they are usually pragmatic pre/post-conditions, not solid theoretical ones. When the code is written well it's only four lines. When it's not i'll have huge sections describing what's going on, which is usually when i decide to re-write it :-)
Anyway, there's another $0.02 for your hat, | [reply] [d/l] |