Agreed with pretty much everything here. My notes:
Read about software patterns - the gang of 4 book and Fowlers book are classics. This will help you read and understand legacy code, and write your own code with understandable structures and naming conventions.
All skill learning inevitably comes with making mistakes that you regret later, and which will make you look dumb. Embrace it. If you have to think too hard to come up with a clever name for a variable, give it a stupid long name - the dev 5 years later working on your code would much rather have a variable with a name so long it runs off the page, but actually describes its purpose accurately, than a short named variable that is “clever”. If you or someone else thinks of a better name later, renaming variables is trivial. Interpreting variable purpose from an unclear name is not. Similarly, make your methods short - really, really short. If you have 10 lines of code and put them each in their own method, great! Maybe it isnt the fastest code to read - but readable method names will make it obvious what each line does, and combining independent methods together is far easier than breaking one massive method into chunks.
TDD (or BDD) is awesome for turning most of the things listed here into habits. It also, ime, makes boring enterprise software development far more enjoyable, since you start by making a long checklist of itty bitty tasks, and then get to check a new one off every 5 or 10 minutes, knowing that the task is done.
The best way to learn how to write better code is pair programming with a more senior developer. Often employers will refuse to budget time for this since “how can we justify paying two developers to write the code one developer could?” The fact is, developing like this typically decreases development time as juniors’ code ends up more readable and with fewer bugs, reducing time spend on fixing bugs later - the most time-intensive part of any software project. If managers still won’t budge - fuck 'em. Do it anyway. Getting someone to critique your code in real time - even for just 30 minutes per day - will rapidly improve your skills.
I wouldn’t recommend the Gang of Four book. Many of the design patterns they espouse are way over complicated from the days of peak OOP. You know, FactoryFactoryVisitor stuff. Usually best avoided.
Agreed. And a lot of it is working around limitations of whatever version of Java was common at the time.
“Visitor pattern” is better implemented as an implementation of Iterator or whatever your language calls that. Everyone knows what “for x in thing” means, but wtf does it mean to “visit” something?
Similarly, make your methods short - really, really short. If you have 10 lines of code and put them each in their own method, great! Maybe it isnt the fastest code to read - but readable method names will make it obvious what each line does, and combining independent methods together is far easier than breaking one massive method into chunks.
I agree with a lot you said and this reads like advice straight from Robert Martins “Clean Code”, but I’ve recently read a discussion between him and John Ousterhout, where John makes compelling arguments for longer, “deeper” functions. I found the discussion very interesting and actually started reading “A Philosophy of Software Design” shortly after. Would recommend!
I think Ousterhout’s observation that deep interfaces are more useful is a very astute one. There is a kind of programmer who finds it satisfying to write lots of boilerplate but it doesn’t make the code maintainable.
Short functions can be good because you then name each short section of code, but a comment can offer that more flexibly.
I did feel like Ousterhout kind of undermined his own “comments go a long way in explaining code in longer functions” argument when his example code featured some incorrect comments, which is exactly what Martin warned about.
Honestly neither of them were really wrong anywhere, they just have a different approach. Sometimes I find Martins code split into too many functions, but halfway through there’s an example where Martins code is imo definitely clearer than Ousterhouts.
Both of their experience is valuable and is best shared, but not taken as gospel I think.
Agreed with pretty much everything here. My notes:
I wouldn’t recommend the Gang of Four book. Many of the design patterns they espouse are way over complicated from the days of peak OOP. You know, FactoryFactoryVisitor stuff. Usually best avoided.
Agreed. And a lot of it is working around limitations of whatever version of Java was common at the time.
“Visitor pattern” is better implemented as an implementation of Iterator or whatever your language calls that. Everyone knows what “for x in thing” means, but wtf does it mean to “visit” something?
I agree with a lot you said and this reads like advice straight from Robert Martins “Clean Code”, but I’ve recently read a discussion between him and John Ousterhout, where John makes compelling arguments for longer, “deeper” functions. I found the discussion very interesting and actually started reading “A Philosophy of Software Design” shortly after. Would recommend!
I think Ousterhout’s observation that deep interfaces are more useful is a very astute one. There is a kind of programmer who finds it satisfying to write lots of boilerplate but it doesn’t make the code maintainable.
Short functions can be good because you then name each short section of code, but a comment can offer that more flexibly.
I did feel like Ousterhout kind of undermined his own “comments go a long way in explaining code in longer functions” argument when his example code featured some incorrect comments, which is exactly what Martin warned about.
Honestly neither of them were really wrong anywhere, they just have a different approach. Sometimes I find Martins code split into too many functions, but halfway through there’s an example where Martins code is imo definitely clearer than Ousterhouts.
Both of their experience is valuable and is best shared, but not taken as gospel I think.
Thank you for your comment. What are the books you mention in point 1?
I believe this is the “Gang of Four” book:
“Design Patterns: Elements of Reusable Object-Oriented Software”
ISBN: 0201633612
https://www.betterworldbooks.com/product/detail/design-patterns-elements-of-reusable-object-oriented-software-9780201633610