Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

I know the general trend against comments explaining how something works, and how it's a good idea to use them only to explain why you're doing what you're doing, but what about using comments as a means of dividing up the code?

Assume you have a script that does a preamble, searches through a bunch of records, prints the records, then closes everything:

// Preamble
... preamble code, say about 10-15 lines ...

// Find records
... sql query ...
... put records into array ...
... some other stuff ...

// Print records
... printing records, 20-30 lines a record ...

// Close everything
...

More of a way to visually divide the code, make it easier to find a certain section. Like if in a month you need to fix the printing code, rather than reading through a couple hundred lines to try and find the right spot, just look at the comments to see where it is.

What actually happens in each section being fairly straightforward and easy to tell what's going on, would this approach to comments be considered good or bad?

Edit: I'm working mostly with PHP scripts, where you either can't put code into functions, or it's impractical to do so. However, the same sort of thing would apply to large class files, with several methods that do related things, like getters/setters, database updates, etc.

share|improve this question
3  
Would you be willing to specify what languages you are basing your question on? I think you'll get very different answers for a procedural, typically-single-file scripting language than you would for C-variants, Java, and the like. –  Philip Regan Nov 10 '10 at 15:30
add comment

6 Answers 6

They're not out and out bad but I would ask if your routine is so long that it has sections that are significant in their own right and need a comment wouldn't you be better breaking it down into smaller routines?

You'd then have a top level routine which was totally readable without comments:

Thing.Initialise
Thing.PopulateFromDatabase
Thing.PrintResults
Thing.ShutDown

Plus it's all reusable now.

I'd also add that generally things like "close everything down" should be obvious from the code and the structure and therefore unnecessary. If the code is This.Close(), That.CleanUp(), TheOther.Disconnect() then you really don't need a comment explaining.

Where I think these sorts of comments are good is in roughing out your design and structure before you start. I find it's good to write the thing out in pseudo code in comments and then remove them as I actually code it. You can then add and amend the design quickly as you are coding without the risk of forgetting what it was you'd decided.

share|improve this answer
2  
+1: I always prefer refactoring that removes the need for a comment. –  Larry Coleman Nov 10 '10 at 15:58
    
What about when you have to do things that don't factor nicely, for example because they depend on almost all the state in the original function? –  dsimcha Nov 10 '10 at 16:44
    
As I said it's not out and out bad, there are just often better alternatives. –  Jon Hopkins Nov 10 '10 at 16:54
add comment

I like this type of commenting. Not everything factors nicely into a separate class or function. For example, if you'd have to pass almost the entire stack frame worth of state to such a function/class, you aren't really be decoupling/simplifying anything by factoring the code out. Even if the code can be factored out, that doesn't mean it should be. You have to weigh the reusability gains and the gains in readability of the individual steps against the fact that excessive indirection can make the overall flow of the code more opaque.

Even if you do separate out the code into a class/function, comments might sometimes be useful to explain at a high level what the code does. Comments are not a substitute for readable code, but even readable code doesn't always summarize its high-level purpose, even if it's well-factored into small functions/classes.

share|improve this answer
add comment

Personally, I'm against this type of commenting but only because most modern code editors allow you to collapse methods making it easier to read. Adding comments therefore tends to at clutter since it no longer contributes to clarifying anything but simply declaring grouping.

C# has a grouping using #region and #endregion which is useful. Eclipse makes decent use of an outline.

However, there's no wrong way to comment code and generally speaking it's not 'worse' to have more comments (not going to pretend you can code faster without it).

share|improve this answer
    
In effect, the #region grouping would be doing the same thing, just makes folding a lot nicer –  Slokun Nov 10 '10 at 20:00
    
Agreed. Though that serves a function, not just sprinkling comments which don't serve any purpose. –  Neil Nov 11 '10 at 10:31
add comment

I think it would be fine IF you have a lot of code that is similiar, e.g. this.setProperty("prop", "val"); over and over again. So, you could have an init() method that had a global properties section, local properties, and session initializers. However, I would still put these in separate methods unless there was absolutely NO chance that that code could possibly be reused.

share|improve this answer
add comment

In a procedural scripting environment, where all code is contained in one file as subroutines, comments describing sections of code would be a must after a certain point, and there's nothing wrong with that.

I'm currently staring at an Applescript that is almost 700 lines long that is about to double in size here pretty soon (other Applescripts I have top over 2000 lines) with dozens of subroutines. Moving code to external files is more trouble than it's worth right now, so section commenting is the better way of managing it all until I find time to improve the situation.

I'm basing my answer on the fact that you specifically used the word "script" in your question, which belies a procedural script as opposed to object-oriented code.

share|improve this answer
add comment

Personally it would be redundant. The reason being is if you were to create a function or class to handle the task then it should be straight foreword to go back and make changes in the future.

share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.