[codethief]

> The second one is ok, but please don't follow the first one as a good example, it takes away the ability to scan the code.

IMO if at all, this type of comment ("Why was X designed this way") should go to the very bottom of the file (maybe with a very short comment at the top of the file referencing it), so it doesn't bother anyone who works on the code on a regular basis. And one could (should) also decrease its verbosity.

EDIT: Confused first and second example

[ainzzorl]

A lot of code files starts with lengthy copyright notices, and no one seems to mind. I find comments at the top very easy to ignore if I work on that code regularly. Also, I don't think I've ever seen comments at the bottom of a file!

I wonder if Protobuf wasn't open-sourced by Google, that comment would've been replaced with a link to a design doc. Google docs weren't a thing in early 2000s when Protobuf was originally written though.

[codethief]

> A lot of code files starts with lengthy copyright notices, and no one seems to mind.

Hmm, maybe I'm the odd one out but I actually find them quite annoying if they're longer than just a few lines.

In any case: People often just scroll past and ignore lengthy comments at the top (maybe precisely because they're used to copyright notices), so I think a short comment at the top like "For design considerations and reasons this code has been written the way it is, see the very bottom of this file" will attract much more attention.

> Also, I don't think I've ever seen comments at the bottom of a file!

True, but how often do you see code comments about design considerations in the first place?