<story><title>Please do not attempt to simplify this code</title><url>https://github.com/kubernetes/kubernetes/blob/ec2e767e59395376fa191d7c56a74f53936b7653/pkg/controller/volume/persistentvolume/pv_controller.go</url></story><parent_chain><item><author>afarrell</author><text>&amp;gt; probably a hell of a lot easier to maintain and manage than splitting the logic up among tens or hundreds of files&lt;p&gt;I&amp;#x27;m only halfway through John Ousterhout&amp;#x27;s book Philosophy of Software Design but I think it agrees with you on this -- that smallness-of-file or smallness-of-function is not a target to shoot for because it prevents the things you build from being deep. That you should strive to build modules which have deep functionality and small interfaces and should contain their complexity within them so the users don&amp;#x27;t have to know that complexity.</text></item><item><author>Klathmon</author><text>I love this! It&amp;#x27;s the &amp;quot;jazz music&amp;quot; of software development. Something which breaks all the &amp;quot;rules&amp;quot; but does so purposefully and explicitly so that it can become better than the &amp;quot;rules&amp;quot; allow.&lt;p&gt;A naive look at this and my head is screaming that this file is way too big, has way too many branches and nested if statements, has a lot of &amp;quot;pointless comments&amp;quot; that just describe what the line or few lines around it is doing, and has a lot of &amp;quot;logic&amp;quot; in the comments which could quickly become outdated or wrong compared to the actual code.&lt;p&gt;Yet at the same time, it&amp;#x27;s probably a hell of a lot easier to maintain and manage than splitting the logic up among tens or hundreds of files, it contains a lot of the inherently complex work it&amp;#x27;s doing to this file, and it is so well and heavily commented that it should be pretty easy to ensure that any changes also keep the comments up to date (after all, any change without changing the resulting comments should show up like a sore thumb, and will most likely prompt the reviewer to look into it at the very least).</text></item></parent_chain><comment><author>TeMPOraL</author><text>I just finished his book yesterday; he has a lot to say about size and comments. For size, your summary is spot-on. I&amp;#x27;d only add that he notes overeager splitting of methods and classes makes code involved in a particular abstraction to be no longer in one place, leading developers to constantly jump around files, which makes it more difficult to understand the code and increases the chances of making bugs.&lt;p&gt;As for comments, this file is essentially Ousterhout taken to the extreme. Still, I think he would have like it, given how critical this file is. In the book, he encourages writing more comments than the current trends would suggest, pointing out that you can&amp;#x27;t fully express abstractions in code, so all the things the code doesn&amp;#x27;t contain - the high-level concepts, the rationale, the caveats - should be documented in comments in appropriate places.&lt;p&gt;Overall, I&amp;#x27;m extremely impressed by the book, and its focus on reducing and mitigating complexity.</text></comment>
<story><title>Please do not attempt to simplify this code</title><url>https://github.com/kubernetes/kubernetes/blob/ec2e767e59395376fa191d7c56a74f53936b7653/pkg/controller/volume/persistentvolume/pv_controller.go</url></story><parent_chain><item><author>afarrell</author><text>&amp;gt; probably a hell of a lot easier to maintain and manage than splitting the logic up among tens or hundreds of files&lt;p&gt;I&amp;#x27;m only halfway through John Ousterhout&amp;#x27;s book Philosophy of Software Design but I think it agrees with you on this -- that smallness-of-file or smallness-of-function is not a target to shoot for because it prevents the things you build from being deep. That you should strive to build modules which have deep functionality and small interfaces and should contain their complexity within them so the users don&amp;#x27;t have to know that complexity.</text></item><item><author>Klathmon</author><text>I love this! It&amp;#x27;s the &amp;quot;jazz music&amp;quot; of software development. Something which breaks all the &amp;quot;rules&amp;quot; but does so purposefully and explicitly so that it can become better than the &amp;quot;rules&amp;quot; allow.&lt;p&gt;A naive look at this and my head is screaming that this file is way too big, has way too many branches and nested if statements, has a lot of &amp;quot;pointless comments&amp;quot; that just describe what the line or few lines around it is doing, and has a lot of &amp;quot;logic&amp;quot; in the comments which could quickly become outdated or wrong compared to the actual code.&lt;p&gt;Yet at the same time, it&amp;#x27;s probably a hell of a lot easier to maintain and manage than splitting the logic up among tens or hundreds of files, it contains a lot of the inherently complex work it&amp;#x27;s doing to this file, and it is so well and heavily commented that it should be pretty easy to ensure that any changes also keep the comments up to date (after all, any change without changing the resulting comments should show up like a sore thumb, and will most likely prompt the reviewer to look into it at the very least).</text></item></parent_chain><comment><author>Klathmon</author><text>Now i&amp;#x27;m squarely in frontend web-app development right now which definitely changes things (mainly the complexity is centered around enabling fast changes&amp;#x2F;additions to the codebase, and not the actual business logic for the most part), but while &amp;quot;deep functionality and small interfaces&amp;quot; sounds good on paper, &lt;i&gt;most of the time&lt;/i&gt; giant files with a few functions exported aren&amp;#x27;t a good way to manage that.&lt;p&gt;Sure, it solves the problem when viewed from the outside. &amp;quot;users&amp;quot; of the software (users being other devs in this case) get a nice small interface and docs that explain how to use it, but internally it&amp;#x27;s much harder to work with. Having everything in one file like this without breaking it into &amp;quot;sub modules&amp;quot; for various parts of the module means that you need to almost have a complete understanding of the module before working on it.&lt;p&gt;In this case, I have a feeling that is a pro not a con. Because this file is so core to the system, and has so much complexity, that breaking it up into smaller parts could cause a dev to feel like they understand it only to find out they don&amp;#x27;t after it&amp;#x27;s released. And it means that any devs that truly do understand it top-to-bottom would just waste a lot of time switching around files if it were split up.&lt;p&gt;Putting it all in the same file here nudges you to really make sure you understand it top to bottom before making any big changes. It&amp;#x27;s intimidating and scary for a reason, because at its core it is a complex piece of code, and dressing it up in &amp;quot;simple code&amp;#x27;s clothing&amp;quot; won&amp;#x27;t help.</text></comment>