Re: Ways of commenting subroutines
by arhuman (Vicar) on Mar 28, 2001 at 13:44 UTC
|
I think almost everything was said in this node (some other interesting things could be found here)
Now For my part, chating with tilly convinced me that explicit
function name, (and obviously code logic)
is definitly something to pay attention to (mainly beccause of the code/comments synchronization problem):
For example your function could be renamed db_check_user_address()
Anyway even if it's obvious : Pay more attention in writing clear code rather than trying to explain complex/strange/bad/obscure code.
NOTE: I've heard dkubb is working on a document, describing good coding practice, needless to say I'm impatient to read it...
(Especially when you see the quality of some of this post...)
Furthermore I see more and more questions about how to write good code? what is more elegant? how much a code should be documented? ...
I then think I'm not the only one who find perlstyle a little bit short.
And I really think that with all the skilled coders around, the monastery could produce a good answer...
"Only Bad Coders Badly Code In Perl" (OBC2IP)
| [reply] [d/l] |
Re: Ways of commenting subroutines
by jeroenes (Priest) on Mar 28, 2001 at 15:51 UTC
|
| [reply] |
|
I have read Code Complete, and I agree it raises some good points,
but seeing as I don't know Pascal (which most of the examples are in)
I find reading the book really frustrating.
I wish he would update the book with some examples from Perl and Java.
UPDATE:
Maybe explaining what I meant would be good, since I am still get voted -- on this ack!
I think that what Code Complete has to say regarding commenting, and construction of code to be well said, and still applicable.
But there are portions of the book, especially Design, where the material Steve McConnell presents
feels dated to me. I don't know Pascal, so talking about the merits of it as a language in his examples
does not elucidate his discussion.
Further, Steve McConnell spends a long portion of his discussion in design talking about modules, when I prefer functions.
Basically I rubbed some people with my opinion and if I did, so be it. I'll take my drubbing, but it's my opinion and I'm not going to change it because this book holds a revered place in some people's libraries.
I still wish he'd update his examples with some from Java or Perl.
| [reply] |
Re: Ways of commenting subroutines
by kal (Hermit) on Mar 28, 2001 at 16:07 UTC
|
I like using pre- and post- conditions a lot of the time. The subroutine should say what it expects, and under what conditions you get a return value, etc. Something like:
sub add_one_to_number() {
# add_one_to_number ($number) : takes a number, returns number + 1
# PRE1: number exists
# POST1: we return the number plus one
my $number = shift;
if (! defined $number) {
return undef; # fail PRE1
}
$number++;
return $number; # success POST1
}
Okay, Noddy example, I know. It marks out under what conditions the author expected to reach these areas. If there is a bug at all, either it's because there is a precondition that we haven't thought about, or we don't successfully reach the postcondition (i.e., incorrect code). Also, putting in carps and things helps you track better what's going on if you follow the PREs and POSTs.
It's one of the things that works for me, anyway :) (obviously, this is in addition to all the other comments and stuff you make!!)
| [reply] [d/l] |
Re: Ways of commenting subroutines
by busunsl (Vicar) on Mar 28, 2001 at 14:09 UTC
|
Most of the time I just use a one-liner for commenting subs.
I try to adhere to the following rules:
Use a self-explaining name for the sub, this will also explain the return value(s).
Use self-explaining names for the parameters, they are pulled in at the top of the sub, so they are seen immediately.
For subs used outside of the modules use pod.
| [reply] |
Re: Ways of commenting subroutines
by Masem (Monsignor) on Mar 28, 2001 at 17:53 UTC
|
Another possibility beyond those talked about here are using comment-to-documentation formats such as Javadoc or Doxygen, which require to have certain key lines in the comments preceeding a function to describe what happens; the comments are still quite readable within the code, and you've got an easy way to make usable documentation outside of the POD mechanism if your project calls for it.
Dr. Michael K. Neylon - mneylon-pm@masemware.com
||
"You've left the lens cap of your mind on again, Pinky" - The Brain
| [reply] |
|
| [reply] |
Re: Ways of commenting subroutines
by mikfire (Deacon) on Mar 28, 2001 at 20:06 UTC
|
I use a similar style, but I also try to include a header
section for the entire module that descibes what it does,
why it was created and any other notes necessary. I usually
include a $Id$ tag as well, just to make the version number
quickly available.
Since I also use CVS for my source code control, I have also
gotten in the habit of, at the very bottom of the POD, to
create a HISTORY section and putting a $Log$ tag in there.
It keeps the checkin history with the file, but doesn't
clutter either the top of the file or
r the POD with a lot.
I also have written code similar to yours to pull my sub headers
out and marginally PODify them. Check out this
node for one of my more interesting attempts ( the first
toy ) at documenting the possible return values for a module.
mikfire | [reply] |
(sacked: inline POD) Re: Ways of commenting subroutines
by sacked (Hermit) on Mar 29, 2001 at 02:24 UTC
|
I use inline POD so I only have to make a change in one place if the function changes:
###################
#
=pod
=item displayform
Usage:
displayform( ['message to user']);
Displays a form for the user to fill out for submission
to ARS Server. Required field for the form is 'problem'
(body text).
There is an optional string parameter to this function
that will display a message along with the form.
=cut
#
###################
sub displayform {
...
--sacked | [reply] [d/l] |
Re: Ways of commenting subroutines
by mbond (Beadle) on Mar 28, 2001 at 22:53 UTC
|
I forget the name of this commenting style, but its supposed to be a standard so that parsers can write the basic documentation for you.
#Requires:
# var 1 to be valid <something>
# var 2 to be valid <something>
#
#Returns:
# var 1 is Preserver/Produces/Destroys
destroys means don't count on it being there, produces means that it is generated in that function and returned to the calling function and preserved means that it will return unchanged.
mbond. | [reply] [d/l] |
Re: Ways of commenting subroutines
by Shadowfax (Sexton) on Mar 29, 2001 at 01:23 UTC
|
i use a modified version of the microsoft flowerboxes
used in Visual BASIC standards. i include the name of
the finction in the top line and it's kinda obvious what
else i do.
i chose this method since the whole thing is easy to read,
easy to modify, and contains all the info you could really
ask for as a person walking into my code. it is usually
more detailed than this, but in the interest of space:
#***<StringToArray>*************************************************
# Purpose: Combine 2 strings into 1 array
#
# Inputs : 2 strings
#
# Outputs: 1 array
#
# Programmer Date Comments
# --------------- -------- --------
# Bob Smith 03/30/01 Created
#******************************************************
as for the comment to write clear code and not
complex/hard to understand/ blah blah blah:
i do not believe that clear or obvious code is
always the best answer to the problem. sometimes
a difficult to see or downright ugly answer is the
perfect trick. if you only write clear code, then
good luck with unclear problems.
sincerely Shadowfax
"A computer is almost human -
except that it does not blame
its mistakes on another computer."
Edited Wed Oct 17 23:37:54 2001 - Footpad
| [reply] [d/l] |
|
I think that even more than other programmers, Perl people have to take most care to write clear code.
Perl code, with heavy use of RegEx, default variables, and syntax trickery, can be an absolute pig to read (all you one-line-coders, take note!). Code readability has to be one of the most important aspects of professional programming.
And it's all very well making a commitment to comment all your code, but the more comments you add, the harder it becomes to maintiain your code. Either you spend too much time adjusting comments when the code changes, or you don't update them at all: (excuse the Java example)
public String getCustomerSSN()
{
// return the customer's SSN<
return customerSSN;
}
becomes:
public String getCustomerID
{
// return the customer's SSN
return customerID;
}
...so the comment (which was already not really necessary) becomes incorrect, making the code less clear.
A good example of code that can be relieved of comments:
if (ftpResponse.charAt(0) == '2')
// ftp result in 200s = success
if a method is added to do this test:
public boolean wasSuccessful(String ftpResponse)
{
return ftpResponse.charAt(0) == '2';
}
...then the original code becomes:
if (wasSuccessful(ftpResonse))
...so the comment is no longer necessary.
(The above examples come from 'Essential Java Style' by Jeff Langr (Prentice Hall PTR) - a very good book that goes through a series of Best Practise rules-of-thumb. In this case, he goes on to say that one of the few places where comments are necessary is when a method has a dependency, i.e. it requires that another method be executed first.)
I know from personal experience that excessive comments can ruin productivity - on one of my first commercial projects, the head programmer insisted that everyone had a ratio of about 2:1 comments to code (that's two lines of comments per line of code!). The design sucked, so despite all these comments the coding was difficult, unclear and underproductive.
On the other hand, when I worked on a project six months later, using the Extreme Programming methodology (XP), where you are supposed to have practically no commenting, we were writing excellent safe code. One of the idealogies of XP was that code always should be as simple and clear as possible. If it could not be easily understood, it was basically wrong.
I don't want to sound like a Software Engineering lecturer, but I certainly want to say that (IMHO) if a problem is unclear, you really, REALLY should not jump in and start coding it. An extra hour spend dealing with the more abstract design will save you 10 hours in coding, maintainance and debugging, and a good design will make any problem more clear...
(waving goodbye whilst dismounting my high horse)...
| [reply] [d/l] [select] |
|
first off, let me say that i do not disagree with you.
that said, i would like to clarify. i was not refering
to a problem unclear in that i did not understand. i was
describing the fact that sometimes the logic needed for
solving a problem is not obvious, is not intuitive, and
quit often is not any clearer than mississippi mud. these
are the times when after you understand the problem, you
can step back and see the issue still resides in a fog
bank, but rather than spend all day looking for a nice
little way to code so that your little sister in elementary
school can understand it, you bang in a quick and dirty
line that solves the problem and a nice descriptive
comment to enlighten your posterity.
in response to the 2:1 ratio... that's called 2 weeks notice
in my book. insanity is not my cup of tea, and that is
clinical right there. if you have not come across a problem
that requires ugly logic, you have not experimented much.
i also fall heavily in support of the "hacker ethic" described
so well by steven levy in "hackers - heroes of the
computer revolution" in that any code you can write,
i will write in less lines. (not a challenge, just philosophy) "bumming" out instructions
is the foundation of computer programming and continues
to drive me as a programmer. if i write something, i
will write it later in less lines. i do not ask you to
agree, but i ask you to not insinuate my "more functionality
with less keystrokes" method is wrong. i do not argue
that you are wrong because you like to write in cute
little snippets with no comments, so please extend me
the same curtesy. thanx, and my what a beautiful horse that was.
Shadowfax
"A computer is almost human -
except that it does not blame
its mistakes on another computer."
| [reply] |
|
|
|
|
|
Re: Ways of commenting subroutines
by Lexicon (Chaplain) on Mar 29, 2001 at 05:50 UTC
|
My current commenting style, although it needs work. You'll have to excuse it's JavaScript-iness, that's all I have handy.
// ========================================================
// COUNT OCCURRENCES (
// STR, // String to search through
// SUB // String to search for
// )
// --------------------------------------------------------
// Counts the instances of SUB in STR. Counts overlapping
// occurrences. Count_Occurrences( 'rrrrr', 'rr') = 4.
// --------------------------------------------------------
function Count_Occurrences ( STR, SUB ) {
var last = 0;
var count = 0;
while ((last = STR.indexOf(SUB, last + 1)) > -1) { count++ }
return count;
}
Update: If you ever spend a year in a country where they don't speak your language, keep a spell checker handy. Alternatively, if my code is used it will only be by non-english speakers, who wouldn't know how to spell 'occurrence' anyway. ;)
-Lexicon | [reply] [d/l] |
|
ouch! you just hit on one of my pet peeves...
bad spelling.
It's "occurrence", not "occurance". Your code may be the
greatest thing in the world since sliced bread, but if
routine names contain spelling mistakes people are going to
believe that the code contains other shoddinesses, thus
you wind up needlessly damaging your reputation.
Worse, client programmers using your code are going to
stumble and trip, because they're going to try and call
count_occurrences and fail miserably.
-- g r i n d e r
| [reply] |