<story><title>On navigating a large codebase</title><url>https://blog.royalsloth.eu/posts/on-navigating-a-large-codebase/</url></story><parent_chain><item><author>sydd</author><text>&amp;gt; Code comments? Nah.&lt;p&gt;This is one of my biggest gripes. Someone (I think uncle bob) said that good code is self-documenting, which is bs in 95% of the cases. Yeah, you don&amp;#x27;t need to document the convertMinsToSecs() method, but most real life codebases are full with edge cases, shortcuts, temporary solutions, half-complete reorganizations. So people use this for writing no comments at all, whereas a few words of comments would save hours of investigative work for future developers working on the codebase.</text></item><item><author>bluefirebrand</author><text>This is a great article. I felt like it was describing a job I recently left, especially this piece:&lt;p&gt;&amp;gt; It’s fine to have less experienced people working on a large system as long as they have the elders overseeing their work. In the world where senior titles are handed left and right, that is often not the case and it’s how you end up with a very fragile system that is suitable for a replacement as soon as it was built&lt;p&gt;Then I got to the advice part of the article and had to laugh.&lt;p&gt;Read the documentation? What documentation. Not a single scrap existed.&lt;p&gt;Look at the tests? I&amp;#x27;d love to, but they never wrote any.&lt;p&gt;Code comments? Nah.&lt;p&gt;Use the IDE for intellisense? Great idea except the database models are in a different project so the furthest you can get is the compiled definitions that were copied into this project.&lt;p&gt;The method that eventually kind of worked was &amp;quot;use the debugger for absolutely everything.&amp;quot;&lt;p&gt;It was honestly one of the most miserable experiences I have ever had.</text></item></parent_chain><comment><author>KajMagnus</author><text>&amp;gt; &lt;i&gt;Someone (I think uncle bob) said that good code is self-documenting, which is bs in 95% of the cases&lt;/i&gt;&lt;p&gt;Agreed. For example, comments about Why-do-this, and Why-Not-do-that can be necessary, even if the code shows &lt;i&gt;what&lt;/i&gt; happens.&lt;p&gt;Imagine you&amp;#x27;re in a taxi, and it suddenly takes the wrong turn, now instead heading towards &lt;i&gt;Surprise-City&lt;/i&gt;. Then — you know &lt;i&gt;what&lt;/i&gt; is happening. You&amp;#x27;re going to &lt;i&gt;Surprise-City&lt;/i&gt;.&lt;p&gt;But would&amp;#x27;t you also want to know &lt;i&gt;Why&lt;/i&gt;?&lt;p&gt;So then it&amp;#x27;s nice if the taxi driver explains Why: &amp;quot;I buy milk to kitten.&amp;quot;&lt;p&gt;I think the &amp;#x27;Linux kernel coding style&amp;#x27; explains comments pretty well:&lt;p&gt;&lt;a href=&quot;https:&amp;#x2F;&amp;#x2F;www.kernel.org&amp;#x2F;doc&amp;#x2F;html&amp;#x2F;v4.10&amp;#x2F;process&amp;#x2F;coding-style.html#commenting&quot; rel=&quot;nofollow&quot;&gt;https:&amp;#x2F;&amp;#x2F;www.kernel.org&amp;#x2F;doc&amp;#x2F;html&amp;#x2F;v4.10&amp;#x2F;process&amp;#x2F;coding-style.h...&lt;/a&gt;</text></comment>
<story><title>On navigating a large codebase</title><url>https://blog.royalsloth.eu/posts/on-navigating-a-large-codebase/</url></story><parent_chain><item><author>sydd</author><text>&amp;gt; Code comments? Nah.&lt;p&gt;This is one of my biggest gripes. Someone (I think uncle bob) said that good code is self-documenting, which is bs in 95% of the cases. Yeah, you don&amp;#x27;t need to document the convertMinsToSecs() method, but most real life codebases are full with edge cases, shortcuts, temporary solutions, half-complete reorganizations. So people use this for writing no comments at all, whereas a few words of comments would save hours of investigative work for future developers working on the codebase.</text></item><item><author>bluefirebrand</author><text>This is a great article. I felt like it was describing a job I recently left, especially this piece:&lt;p&gt;&amp;gt; It’s fine to have less experienced people working on a large system as long as they have the elders overseeing their work. In the world where senior titles are handed left and right, that is often not the case and it’s how you end up with a very fragile system that is suitable for a replacement as soon as it was built&lt;p&gt;Then I got to the advice part of the article and had to laugh.&lt;p&gt;Read the documentation? What documentation. Not a single scrap existed.&lt;p&gt;Look at the tests? I&amp;#x27;d love to, but they never wrote any.&lt;p&gt;Code comments? Nah.&lt;p&gt;Use the IDE for intellisense? Great idea except the database models are in a different project so the furthest you can get is the compiled definitions that were copied into this project.&lt;p&gt;The method that eventually kind of worked was &amp;quot;use the debugger for absolutely everything.&amp;quot;&lt;p&gt;It was honestly one of the most miserable experiences I have ever had.</text></item></parent_chain><comment><author>spinningslate</author><text>my priority for comments is that they should answer &amp;quot;why?&amp;quot; and &amp;quot;why not?&amp;quot; questions.  Why does the method&amp;#x2F;function do it this way?  Why didn&amp;#x27;t it choose that other, perhaps more obvious route?&lt;p&gt;That&amp;#x27;s not necessary in every case.  But it&amp;#x27;s true in a good number of them.  The code alone can never tell you that - but it&amp;#x27;s often invaluable during evolution&amp;#x2F;refactoring.</text></comment>