Long ago, I got a quick glance at some code (PERL... urp) one of my managers was writing and was stunned by the banner/heading system he used in his code. I didn't get a chance to delve into his code in detail, but just from the banner comments on the screen I could easily tell what the code was meant to do, even from far away.
Unfortunately that was long ago and our conversation at the time did not lend itself to me saying, "Yeah, well forget about our dot-com startup going down the toilet, can I take notes on your coding style?"
Years later, I've not yet achieved a high-level comment style that has the clarity as the (probably now mythical) code I saw that day.
When I say, "banners", I'm referring to the high-level block divisions/headers many coders use to create higher-level devisions in their code. They're usually made up of simple ASCII dashes, slashes, equal signs, etc. In my current daily-use language, one code banner/header hierarchy might be:
# ========================================================
# = Header 1
# ========================================================
# --------------------------------------------------------
# - Header 2
#---------------------------------------------------------
# == Header 3 ============================================
# -- Header 4 --------------------------------------------
# Header 5
and all the usual variations.
Although my searches have turned up nothing noteworthy, surely somewhere on the web someone's attempted to collect examples of these and present them in a systematic manner?
Can someone point to banner comment style "systems" they've found useful? I'm not thinking of "Oh, I like the ones using asterisks", but more of an overall strategy of styles that makes high-level code construction quick and easy to understand as well as easy on the eyes? Picking a preferred system from examples would be easier than comparing descriptions, obviously.
Note: I'm not interested in the contents of the comments per se, but the "flair" used on the comments to provide a clear indications of overall code content and organization.
A little late to the party here, but in case this question is still nagging at you after the past 11 years...
// ────────────────────────────────────────────────── I ──────────
// :::::: K A R Y C O M M E N T S Y S T E M ::::::
// ───────────────────────────────────────────────────────────────
Your former manager was most likely using Kary Comments, formerly known as the Kary Foundation's Standard Comment System (KFCS) by Pouya Kary. In it's earliest form, it was indeed quite pretty to look at - inspired by the use of negative space in UI (ie, white space feels refreshing and uncluttered).
from the coding standards introduction:
Kary Comments introduce enough indentation and empty lines that when dealing with a code, the users focus on the context that is relevant to them. They get the chance to breath every once in a while and that is a big help.
//
// ─── OBSERVATIONS ─────────────────────────────────────────────
//
The utility of the system is debatable, and most of the earlier formatting guidelines it introduced are no longer of much value with the evolution of improved intellisense, code colorization, mini maps, and collapsable regions in IDEs. Something the creator acknowledged as well in a more recent update:
The whole things is now much much more clean. After years of using and applying Comment V to my life and writing more than a 100 code bases with it, I've applied what I've learned to the new version. There are now only two comment types: Section Comment and Line Comment. All the others were shiny objects that in time were obsolete and useless to the actual projects.
//
// - - PRETTY BUT PAINFUL - - - - - - - - - - - - - - - - - - - - - -
//
Admittedly, it was/is pretty to look at, but the application of it - actually using the system - was such a nightmare, it required aspecial GUI editor to inject the comments into your source. End result was ~70% LOC attributed to comment decorations and white space.
// ─── How it looks now ──────────────────────────────────────────────────── ✣ ─
The current system hsa dropped all but a couple of the most basic banner formats, and the GUI editors deprecated in favor of the VSCode extension Comment 6.