Hacker News Reader

Comment by rocqua | Hacker News Reader

A type of comment I miss here are "section headers".

I tend to organize my files into paragraphs or even sections of paragraphs. I often use "section headers" to distinguish these. It is essentially a weaker version of splitting a file across multiple files.

For example, I am working on a very simple pre-processor, and I have split it into 4 sections. The first is unmarked and presents the public interface. After that is a section marked simply by the comment "Lexer", after that is a section marked by the comment "Parser", and finally there is a section marked "TURN BLOCK BACK INTO TEXT". That last one should probably be changed to something like "Process result of parsing".

Sometime, my 'paragraphs' of code also get a short line comment explaining what the entire paragraph does. I guess that would generally fall under the 'guide comment' category.

View on HN

In C# there are #regions which are collapsible in the editor. Linters these days complain that they shouldn’t be used.

Obviously if yin gave 9 functions that belong in 3 groups of 3, you can argue that they should have a header but for most code I’d argue that more smaller things wins. I’d rather split it into 3 types and document the types even if the purpose of the split was mostly to get something to attach the comment to. The biggest issue with “free floating” comments (that aren’t for a statement, method, type or other code element) is that they tend to rot in the worst ways. Moving the code with refactoring tools won’t move the associated headers. When adding new code it’s easy to add under the wrong heading etc.

#regions are great. Syntax is the one issue (as you pointed out) but it could be better by adding a special comment code syntax and removing the closing. For example, a comment like

    //== wrappers for inherited functions

where the equals work like in markdown headers, and the region continues until the end of scope or a new region.

Yep I use these but I thought that they are a form of guide comments.

Why not have each of those sections as a separate file?

It's a balancing act of-course. The total file is ~200 lines at the moment, breaking it up would create some very small files, and generate a lot of 'including' boilerplate.

Moreover, it would make it more difficult to understand the whole thing. The lexer and parser are closely coupled (by the data type for the tokens) and the parser and 'processor' are closely coupled by the data type of the syntax tree.

I could still see it happen that it does get split, and there are certainly coding styles that would have split this without question.

That works if you need to usually only work within a section. However, in many cases switching files can be more distracting than scrolling to a different section in the same file.

Sections are the step before separate files for me.

Reply on news.ycombinator.com