Ask HN: Doc-comments... over each code block or grouped at the end?
I'm having one of those moments when you need some light...
I'm writing a big project, and by definition it's on an interpreted language.
Lets say I did a "documentation from comment blocks" system too, because this language did lack such functionality on a standard way.
And now, I've to choose if I let the documentation blocks stay _over_ each function, or I group all the documentation, at the end, after the code and normal comments.
I did just benchmarked this change, and there are performance gains grouping it at the end, and inserting a "return" (or "exit" in the case of apps) before the documentation.
My question here is because, working with the code in both ways, I'm still not sure which one I prefer.
On one side, seeking for code, and seeking for code context, I prefer to have all without splits.
On the other side, when reviewing code, sometimes you need to remember some details on the interface (or update it's description) and you need to move to the end of the file, and move back when done.
I've see some frameworks using separated files (even extensions) for doc-comments and code, but at the end of the day I think it's too much hassle for the benefices...
What's your opinion about this?