Manifesto for code beacons use

A codebase is an ocean. It's vast, some parts are undiscovered and it's ever moving.

A wise sailor shall make good use of beacons to get his way around.

Management and career concerns should not be a motivation to place or search for a beacon. Quality, maintainability and ease of work should.

Codebeacons are specific comments that follow these conventions:

Searchability

One of the main goals of codebeacons is for them to be easily searchable when doing a full text search of a codebase repo(s). Codebeacons make a codebase more searchable.

No specific tooling shall be needed to use them. A simple grep, ctrl + shift + F or Notepad++ "Find in subfolders" must stay enough.

You then browse and search the full text search result for a beacon you are looking for.

Additional tooling can be handy, of course, but it shall never be essential, so beacons stay operational in lean environments like is a container in production.

Rarity

There must be only one occurrence of the same beacon in a codebase. Beware not to copy/paste a codebeacon when you copy/paste some code. Some tooling in an IDE/CI pipeline can help checking and enforcing that rule.

Codebeacons shall not get too numerous in a codebase. They must be well thought and carry real maintenance value. For example, if you are looking for a specific HOWTO beacon, you will typically make a full text search of the // HOWTO text through the code base. You will then have to browse that list. The shorter the list, the faster you will find the beacon you were looking for.

Also, keep in mind that finding out that a beacon is NOT present in a codebase should stay easy. A full text search of a codebeacon must be quickly browsable.

Placing a beacon

It's not easy to place a beacon. The sailor must stop, think and pay close attention.

Where is the best place to place it?

Here are some guidelines:

Ask yourself

• Where would I prefer to teleport myself, a colleague or an AI if I run into this problem again?
• What keywords should I put into this new codebeacon's description so it will be easy to find when I, or others, will be looking for it?
• If you have spent a long time figuring out how to solve a problem. If you have an AI try and try again before nailing it. If you had to dig into Stackoverflow or had to ask a question there. If it was hard to find in a codebase you are new to. Place a codebeacon there.

Codebeacon types:

• // HOWTO is technical. It marks a place where a specific technical subject is managed. That subject can be tweaked there and maintained.
• // RULE is functional. It should be labeled in the main language used by the maintaining team and refer to the identifier of a business rule, e.g. // RULE SPEC_MSG_WELCOME_SENT_03: The user welcome message is sent.. It will be labeled "REGLE" for example if your team is French.
• // TEST refers to a unit or an end-to-end test. Like // RULE it should be followed by the business rule identifier that's being implemented, when it's relevant. If you have got a RULE, a TEST and a business rule in a specification sharing the same identifier, you have tightly bound that specification to the code.

You can, of course, add your own types of beacons, like // PROMPT for example. Just make sure it does not get too complicated and that the whole thing stays easy, obvious and self-explaining to a new member of the team.

A codebeacon content description:

A codebeacon is made of 3 to 4 parts. For example:

// HOWTO Authorization: Where the password is hashed

1. A codebeacon starts with a //   in a C like programming language. This would become -- //   in a SQL script, for example.
2. Then, the HOWTO or RULE part is the beacon itself.
3. Authorization : This third part, before ':', is optional. That lets you group related HOWTO beacons. On the other hand, for RULE and TEST beacons, that third part is a business rule identifier.
4. "Where the password gets hashed". The last part is the beacon description itself. Keep it on one line only.

Setting well the third and fourth parts will make it easy to search and browse the result of a full codebase text search.

The sailor, placing code beacons along his journey, builds a map of the codebase that is well labeled and a great tool to set a course.