Divisional/Sectional comments, good or bad?

Question

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.

Answer 1

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.

Answer 2

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.

Answer 3

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).

Answer 4

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.

Answer 5

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.

Answer 6

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.