Horizontal Lines in Comments

Question

I realize that this is largely up to personal preference, but I'm curious whether there are some clear drawbacks to the following;

I find myself constantly dividing source code into logical groups (via "comments") within the same file. For example:

---

//----------------------------------------------------------------------------
#include "..."
//----------------------------------------------------------------------------
#include <...>
//----------------------------------------------------------------------------
#include <boost/...>
//----------------------------------------------------------------------------
#include <os-specific/...>
//----------------------------------------------------------------------------
namespace
{
    void Foo()
    {
    }
}
//----------------------------------------------------------------------------
namespace
{
    void Bar()
    {
    }
}
//----------------------------------------------------------------------------
namespace
{
    void Baz()
    {
    }
}
//----------------------------------------------------------------------------
int main()
{
}
//----------------------------------------------------------------------------
//This file ends with a new-line.

Or:

//----------------------------------------------------------------------------
#ifndef FOO_HEADER_INCLUDED
#define FOO_HEADER_INCLUDED
//----------------------------------------------------------------------------
#include "..."
//----------------------------------------------------------------------------
namespace Foo
{
    void Bar();
}
//----------------------------------------------------------------------------
#endif
//----------------------------------------------------------------------------
//This file ends with a new-line.

---

I've been reading through some alien source lately and I've noticed that virtually no one does this.

The only argument that I could come up with against this sort of "division" is when you physically print source code in portrait-mode where your divisors (if longer than ~80 characters) will get line-wrapped. This is a non-issue in landscape-mode, though.

To be honest, I don't even know why or when I started doing this. Are there any other cons to this OCD of mine?

In addition, for me, this sort of behavior is language agnostic; I was writing a shell script the other day and noticed the exact same behavior pattern.

Answer 1

It looks to me your not using a good IDE. For instance, you can use #regions in VS to group your code. And its much easier than your methods.

Answer 2

Some of us do use them, although maybe not as liberally as you do. See my answer to this question.

Answer 3

Regions are a much better way to divide up code. The company I'm at now has a policy against "flowerboxing" (I.E. surrounding things with /* and ****/ comments) and I'm sure it also applied to horizontal bars.

I'd stick with regions, makes things look much nicer.

Answer 4

I used to do something a lot like that a long time ago. I'd have section headings for the block of includes, declarations, functions, and so forth.

There's a few reasons that I quit doing that:

1. It's one more thing to maintain. You need to remember to add them when you write new code and take them out when you delete stuff. I'd rather spend the mental effort on the code itself, not obsessing over whether something is big enough to warrant a break or not.

2. Some things defied easy classification. Suppose you want to nest a small class inside a function. Are you really going to add a line like that in the middle of your function?

3. Smarter editors made it easier to navigate around in the code. Originally, they were kind of nice land marks when scrolling up and down through a file to find things. But in Emacs, I skip around a lot with incremental searches and tags files. And on the occasions when I use an IDE it shows me the pieces of the file on the side and let me hop to them with a click.

4. As I got better, I moved to smaller, less monolithic modules. These days, I'll just move stuff to a new file rather than add a new section to an existing source file. The files themselves provide the logical grouping. Each file is a tight, cohesive unit -- why break it up?

5. I switched to using Javadoc/Doxygen style comments consistently. These are more descriptive than random horizontal lines, and I've also come to find that they look much nicer in the code, too.

Answer 5

In C source files, I have a template which splits the files up into sections such as #defines, typedefs, static (file-scope) variable definitions and function prototypes, public functions and static functions, etc. (Similarly for C header files). These are delimited by a line of '='.

Unlike the question above, these aren't created in order to group existing blocks of code. I start with these sections, as it provides a useful structure for each file, and dictates where to put the code I'm creating.

I also have a line of '-' between each function, and occasionally between logical groupings in other sections as necessary.

If nothing else, I find it useful to be able to see where functions begin and end when scrolling through the file.