

Ask HN: Doc-comments... over each code block or grouped at the end? - txutxu

Hi,<p>I&#x27;m having one of those moments when you need some light...<p>I&#x27;m writing a big project, and by definition it&#x27;s on an interpreted language.<p>Lets say I did a &quot;documentation from comment blocks&quot; system too, because this language did lack such functionality on a standard way.<p>And now, I&#x27;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.<p>I did just benchmarked this change, and there are performance gains grouping it at the end, and inserting a &quot;return&quot; (or &quot;exit&quot; in the case of apps) before the documentation.<p>My question here is because, working with the code in both ways, I&#x27;m still not sure which one I prefer.<p>On one side, seeking for code, and seeking for code context, I prefer to have all without splits.<p>On the other side, when reviewing code, sometimes you need to remember some details on the interface (or update it&#x27;s description) and you need to move to the end of the file, and move back when done.<p>I&#x27;ve see some frameworks using separated files (even extensions) for doc-comments and code, but at the end of the day I think it&#x27;s too much hassle for the benefices...<p>What&#x27;s your opinion about this?
======
Spoom
If there's a benefit to putting comments at the end, why not remove the
comments entirely in the production version (i.e. minification)?

~~~
txutxu
I'll discard using separated files, because that supposes the double of files.

    
    
        $ echo $(( $( find ./src -type f | wc -l ) * 2 ))
        938
    

And growing each day...

I've make a cli tool to query the docs once everything is installed, it should
not be too much work to adapt to the change.

That's the main reason.

I love minification where it hurts, and I'll consider it for "runtime"
version.

But my doubt is more about the "development" stage of the code, when you work
with it.

update: edited previous no-sense

