I find I often write code in comments first w/ the business logic, and then flesh out the comments with actual code.
Please do not attempt to simplify this code
341–350 of 647 posts
Re: Please do not attempt to simplify this code
#342someone please introduce idris to the k8s team.
Re: Please do not attempt to simplify this code
#343Earlier quoted context omitted.
For me, it's less about number of files than it is "hoeany files do I have to open to figure out how something works? How many levels of indirection do I have to keep in my head?" I started out writing low-ish level code. Motion control, image processing, digital imaging, and the application level code that coordinated it all. I've steadily moved up the abstraction tree over the last 13 years and there's one thing I…
> [how many] files do I have to open to figure out how something works? With jump-to-definition editor integration, who cares?
Anyone who actually worked with code requiring so much jumping.
I did, in an IDE, and I can tell you, jump-to-definition removes the problem of "what file do I have to open now?", but still leaves you with the questions like "where am I?", "how did I get here?" and "what was I trying to understand, again?", which you start asking yourself after ~sixth jump.
Re: Please do not attempt to simplify this code
#344Ignoring the initial boilerplate (license, imports) and the request to preserve the verbose ("space shuttle") style, the first line is: // Design: // // [... 4 paragraphs of English prose // explaining goals and intent... ] That's exactly the type of comment that should be at the beginning of most files!
As a novice programmer, I was absolutely stunned that this was not standard practice. A typical source file provides zero context, background on the subject, pointers to reference material/blog posts/books explaining the concepts, information on how it fits into the program's 'bigger picture', or (most importantly) the thought process that resulted in the file (i.e., why the choice was made to do _this_ rather than _…
You may want to checkout the python standard library files. heapq.py, for example, has some amazing documentation in it:
Re: Please do not attempt to simplify this code
#345Although I think this is great, this reminds me of a talk Bryan Lunduke did where he says CS/software development is not a profession yet. I love the flexibility software devoplmentgives to every cs, programmer, developer but when you think more about it, that is not the same for other jobs/professions. Professions have standard guideline, procedures to follow. Everyone is doing any language they want, design pattern…
I would say that "Everyone is doing any language they want, design patterns they just read from a random article, 100s of tutorials on one subject" is far from being true anyway. That might be true if you live in a cave but when you are working on a team of 6-8 people with a team lead then basically none of that is true and you are forced to follow others' decision and everything is decided for you (instead of you to…
> That might be true if you live in a cave but when you are working on a team of 6-8 people with a team lead then basically none of that is true
Yes, I agree if you have an established team and there is a strict hierarchical development cycle/roles then rules will be enforced. But how about other team dynamics or lone developers that push their code into the world. How many js libraries import explicitly or implicitly an addition library (too many to count on top of my head but not enough to bother writing a script for you to show). There is a lot of bad code out there that were created by bad untrained tech managers and lone coding wolves because some standards have not yet been refined yet or agreed upon(standards like ssl, aes encryption).
> liberal agenda?
You lost me there? And maybe I lost myself as well
> Uncle Bob When I said Bryan, i misspoke and was refering to Uncle Bob. But do you agree with self-imposed or external? They lead down very different paths
Re: Please do not attempt to simplify this code
#346Earlier quoted context omitted.
As a novice programmer, I was absolutely stunned that this was not standard practice. A typical source file provides zero context, background on the subject, pointers to reference material/blog posts/books explaining the concepts, information on how it fits into the program's 'bigger picture', or (most importantly) the thought process that resulted in the file (i.e., why the choice was made to do _this_ rather than _…
There's plenty of good reasons to not write 95% of code with big walls of explanation. The first is a matter of cost: Writing a good explanation around everything is very expensive to do at first. A whole lot of the custom code you find in random companies, from the shiny SV startup to the old enterprise, is unimportant, cobbled together pieces. We have no idea of whether we are writing code that will be thrown away…
> This is not to say that there aren't reasons to write large comment blocks, or architecture documents, but that they are often better written not while the system is being first built, but later, in a maintenance cycle, when someone already had wished for the comments, and has regained the knowledge the hard way.
I don't think the "Lean Manufacturing" approach works here. By the time someone "pulls" you for a comment, you've already lost the most important knowledge that should go into the comments - why the code is the way it is. Maybe you'll recall it when asked, hopefully not missing anything crucial. Meanwhile, comments are extremely cheap to write as you're writing the code, and even before you're writing the code (you did spend the time thinking about what you'll write, and aren't just "coding from the hip", right?).
Re: Please do not attempt to simplify this code
#347Earlier quoted context omitted.
I assume everyone who splits code into smaller pieces use modern IDEs that makes it trivial to navigate to functions by clicking them etc. I say this because I'm always astonished by the number of "modern" programmers who refuse to use IDEs.
> I assume everyone who splits code into smaller pieces use modern IDEs that makes it trivial to navigate to functions by clicking them etc. That's... not the point. Jumping around is. Imagine reading this comment thread on a bizarro-HN, where you only get to see a short camelCased summary like: debunk(this.previousComment), and have to click to open each comment in a new tab. This is how jumping around small functio…
> That's... not the point. Jumping around is.
There is a tradeoff: Small functions make high-level logic clearly visible and easy to find, at the price of forcing you to jump around when you want to dive into implementation details. Putting everything into one big function lets you follow all the implementation details without jumping, at the price of making you read everything to actually understand what the code is doing.
The latter is the biggest price you can possibly make me pay. Jumping around is a minor inconvenience.
Re: Please do not attempt to simplify this code
#348Earlier quoted context omitted.
As a novice programmer, I was absolutely stunned that this was not standard practice. A typical source file provides zero context, background on the subject, pointers to reference material/blog posts/books explaining the concepts, information on how it fits into the program's 'bigger picture', or (most importantly) the thought process that resulted in the file (i.e., why the choice was made to do _this_ rather than _…
> As a novice programmer, I was absolutely stunned that this was not standard practice. I agree with your point, and I will be benefit from this style if it were the standard, too. But don't you think a good community culture can make people maintain a good git history for this purpose? My daily job is a Linux kernel developer. I found that source codes are only the "What" part, git comments can and should state the…
I've never seen a git commit comment describing the "why" of code. "Added foo.\n\nImplemented az Bar because of blorgz." isn't nearly enough of a rationale, and that's the best description I see people making.
Also, the whole point of putting something in a comment is that you have to read it when working through code around that comment. Putting a note in a commit log instead ensures that crucial information important to the code will not be visible, and most likely not read at all, when working on that code.
Re: Please do not attempt to simplify this code
#349Earlier quoted context omitted.
I think your desire is right, but think about this every time you create a file, and how much slower your work would be. The question then becomes: "how much commenting exactly is needed before this becomes more time than the technical debt it creates? I think this type of summary should not be per source file but per package/folder/module/project. A high-level developer overview with sufficient depth will also help…
How long does it take you to write a sentence?
Sometimes a lot. Because what I'm really doing in my head then is the design work (writing a sentence actually helps with that) - the work that's actually necessary to write the code well.
When I read something saying "writing thoughtful comments is too much work" I really read this as "thinking about the code you write is too much work, it's better to write whatever crap that first comes to mind".
Re: Please do not attempt to simplify this code
#350Ignoring the initial boilerplate (license, imports) and the request to preserve the verbose ("space shuttle") style, the first line is: // Design: // // [... 4 paragraphs of English prose // explaining goals and intent... ] That's exactly the type of comment that should be at the beginning of most files!
Sure, and then the next day the whole thing is just a long boring text which has no correlation to reality because the business rule changed and the developer next to you refactored the code.
If the developer next to you refactored the code without refactoring the comments, they did a shit job. Period. They need to be told to go back and fix it.