Avoid These 35 Habits That Lead to Unmaintainable Code(linkedin.com)
linkedin.com
Avoid These 35 Habits That Lead to Unmaintainable Code
https://www.linkedin.com/pulse/avoid-35-habits-lead-unmaintainable-code-christian-maioli-mackeprang
45 comments
jQuery doesn't report some "errors", for example when a selector doesn't match anything.
MySQL doesn't throw an exception or write to an error log when a query matches zero rows, seems silly to throw jQuery under the bus because the programmer doesn't understand a library.
Ahhhh... "errors"
#36 - believing that slavishly adhering to simplistic lists can help you write solid code.
Can somebody change the title? It sounds so much like clickbait garbage that pollutes other parts of the Internet.
It should be: "This man got lost in an unmaintainable codebase and you won't believe what he did next" ;)
"There are only two hard things in computer science. #3 will shock you!"
Appreciate the sentiment but there are literally 35 things to avoid listed and the submission is the same name as the article title.
> If the original title begins with a number or number + gratuitous adjective, we'd appreciate it if you'd crop it. E.g. translate "10 Ways To Do X" to "How To Do X," and "14 Amazing Ys" to "Ys." Exception: when the number is meaningful, e.g. "The 5 Platonic Solids."
> Otherwise please use the original title, unless it is misleading or linkbait.
Quoted from https://news.ycombinator.com/newsguidelines.html - I think this is pretty clearly a case where it is preferred to not use the original title.
> Otherwise please use the original title, unless it is misleading or linkbait.
Quoted from https://news.ycombinator.com/newsguidelines.html - I think this is pretty clearly a case where it is preferred to not use the original title.
Oh man, totally missed that part. For some reason I thought it was preferable to keep original title. /concede
Does that matter? Is the policy to not change clickbait titles when they are technically correct?
Too much work, a more practical approach is to write the code twice.
But the question is: what if you consistently write poor code even when rewriting? Doing something again and again with no change is called insanity :)
Wow, that's quite the butchering of the quote, which is itself untrue[1] and often attributed incorrectly[2]. But I get your point. :)
1: https://www.psychologytoday.com/blog/in-therapy/200907/the-d...
2: https://www.quora.com/Did-Einstein-really-define-insanity-as...
1: https://www.psychologytoday.com/blog/in-therapy/200907/the-d...
2: https://www.quora.com/Did-Einstein-really-define-insanity-as...
Wow, that first link just seems like they're being incredibly pedantic. I seem to remember similar issues with Psychology Today previously, meh. None of these pop-psych rags are particularly good.
Step 1) Don't read a article without any empirical evidence or control group to support opinionated rules.
Agree about random articles, but disagree about empirical evidence. Software engineering at the code level is a craft, not a science. I don't have time to wait around for empirical evidence to land, and when it does, it's likely to be invalid because the experiment environment can not possibly represent the diversity of environments in the real world.
I don't need data to tell me how to run a team, I need people who can discuss their experience like grownups and reach a palatable consensus on how to operate and then get on with it.
I don't need data to tell me how to run a team, I need people who can discuss their experience like grownups and reach a palatable consensus on how to operate and then get on with it.
I would have to disagree with you. Software [Engineering] is a science you just treat it like a craft.
I'm sorry, but you are deluding yourself. Like many technical people you take comfort in objectivity, but science is expensive and require stable foundations. You need something as unyielding as the laws of physics to make real scientific progress, and even then things get really messy fast when you look at things like nutrition where variables are difficult to isolate and experiments hard to design.
Look at the trouble Economics has being taken seriously as a science. Now consider how fast hardware/software moves compared to economic change.
Software engineering methodology is not tractable to science, there is no signal, only noise. If you disagree, don't blame it on me, show me the results and how you apply them.
Look at the trouble Economics has being taken seriously as a science. Now consider how fast hardware/software moves compared to economic change.
Software engineering methodology is not tractable to science, there is no signal, only noise. If you disagree, don't blame it on me, show me the results and how you apply them.
Development of software is not science. Mathematical work on algorithm could be called science, in the sense 'mathematics', but very little part of programmers' work involves such mathematical thinking.
This is pretty much sums up why software development is - let's be polite - not quite as streamlined as it could be.
CS has far too many clever people passing off random opinions and preferences as Best Practices, and far too little empirical testing of anything anyone recommends or does.
CS has far too many clever people passing off random opinions and preferences as Best Practices, and far too little empirical testing of anything anyone recommends or does.
Linked FTA, book about software dev based on empirical studies
https://www.amazon.com/Making-Software-Really-Works-Believe/...
https://www.amazon.com/Making-Software-Really-Works-Believe/...
Lovely book (Read it cover to cover a couple of times) and a step in the right direction for the Software field.
I want to provide a counterargument to #4
'Be strict about best practices even if they seem negligible' is horrible advice.
I often run into cases where something needs to be laid out differently to what the 'best practices' recommend for the sake of readability. I've worked with several popular linting configs for Javascript and over time I've found myself or my team paring them back to just the basics in order to make them usable.
Even the basics provide dubious value in my opinion. A basic linter provides great value if you hire droolers that can't figure out basic indentation. But if you're doing that then you have serious problems and no amount of corralling is going to save you.
Past that, I've never once seen any real value come from something like mandating semicolons, or a lack thereof. I feel like actually caring whether the file you're opening has or doesn't have semicolons is a clear sign of an inexperienced programmer. It makes zero difference to my workflow, and IME experienced devs will just carry on whichever style is already in place without even a second thought, linter or no.
In my experience the absolute worst case scenario in terms of code readability (assuming you haven't hired anyone completely incompetent) is when your dev team is twisting themselves in knots trying to adhere to linter rules when they should just trust their instincts about what is readable and what is not.
'Be strict about best practices even if they seem negligible' is horrible advice.
I often run into cases where something needs to be laid out differently to what the 'best practices' recommend for the sake of readability. I've worked with several popular linting configs for Javascript and over time I've found myself or my team paring them back to just the basics in order to make them usable.
Even the basics provide dubious value in my opinion. A basic linter provides great value if you hire droolers that can't figure out basic indentation. But if you're doing that then you have serious problems and no amount of corralling is going to save you.
Past that, I've never once seen any real value come from something like mandating semicolons, or a lack thereof. I feel like actually caring whether the file you're opening has or doesn't have semicolons is a clear sign of an inexperienced programmer. It makes zero difference to my workflow, and IME experienced devs will just carry on whichever style is already in place without even a second thought, linter or no.
In my experience the absolute worst case scenario in terms of code readability (assuming you haven't hired anyone completely incompetent) is when your dev team is twisting themselves in knots trying to adhere to linter rules when they should just trust their instincts about what is readable and what is not.
Having a standard style is valuable precisely because it's a waste of time to debate or care about this sort of thing. The value of being strict is that tools can do a strict formatting automatically with zero human input.
In other words, for this sort of style stuff, a formatter that everyone uses is much better than either a linter or a "trust your instincts" approach.
In other words, for this sort of style stuff, a formatter that everyone uses is much better than either a linter or a "trust your instincts" approach.
I can't upvote this enough.
We decided to go with a given set of rules for linting at the project start and problems due to limitations by the linter have been extremely rare, in which case we've updated the rules because we can motivate a change.
Of course, a tool like 'go fmt' is far superior to common linters, as most third party packages look the same as your own code.
Of course, a tool like 'go fmt' is far superior to common linters, as most third party packages look the same as your own code.
Yep. I think go fmt is the most state of the art thing in Go, and that every language should prioritize having the something similar built in.
> Adding “TODO” comments is a quick way of making sure you don’t miss anything.
Or is it a quick way of making sure you have a codebase littered with TODO comments? :D
(Though even there, at least they serve as documentation about what you didn't do initially, so it's more helpful than nothing.)
Or is it a quick way of making sure you have a codebase littered with TODO comments? :D
(Though even there, at least they serve as documentation about what you didn't do initially, so it's more helpful than nothing.)
If it needs to be done, and you are going to do it, then don't pollute the code base with your personal TODOs. I shouldn't see it, because it should be done by the time I get to it. If you want to put it in the code base, at least put your name in the TODO, so I know who to contact and remind that something was missed.
If there is something that needs to be done and you are not going to do it -- the code is the worst place to put it. Basically, what you are saying is that you have a design in mind and want someone else to finish it. If you really can't trust your coworkers to refactor the code and build good designs on their own, use a different communication mechanism. The better thing is to forget about your long term plans, leave the code as simple as you can and trust your coworkers.
If there is something that needs to be done and you are not going to do it -- the code is the worst place to put it. Basically, what you are saying is that you have a design in mind and want someone else to finish it. If you really can't trust your coworkers to refactor the code and build good designs on their own, use a different communication mechanism. The better thing is to forget about your long term plans, leave the code as simple as you can and trust your coworkers.
More important than any of these tips is how to factor code so that it can combine in compact ways without multiplicative complexity with each option added. Without that continuing along any path will lead to an unmaintainable mess.
Software development is one of those areas where everything has an "it depends" in front of it. If you know what you're doing you don't need generic advice and if you don't it won't help you.
Some random thoughts:
#1 Anyone who has worked on a large code base knows it's littered with TODO comments. Either do it or don't do it.
#3 Yet again half of Knuth's quote. If performance matters don't wait. If it doesn't then it doesn't. But after the fact optimization rarely happens, is more expensive and won't get you there. Don't do unnecessary optimization at the end of the project and don't them them in the beginning either. The necessary ones need to be thought out in advance (choice of right data structure, algorithms, tools) and are difficult to change after the fact.
#4 Arguing about style isn't a good use of time. There has to be some measure of consistency/coherence in a code base but it's easy to take too far.
#7 There's a fine line between a best practice and a cargo cult. Don't do something just because it's a best practice. Do it because you understand the relationship between the practice, the circumstances, and the results.
#17 There's a positive side to personal attachment to the code. You care about it. Also did #34 just state the opposite?
Some random thoughts:
#1 Anyone who has worked on a large code base knows it's littered with TODO comments. Either do it or don't do it.
#3 Yet again half of Knuth's quote. If performance matters don't wait. If it doesn't then it doesn't. But after the fact optimization rarely happens, is more expensive and won't get you there. Don't do unnecessary optimization at the end of the project and don't them them in the beginning either. The necessary ones need to be thought out in advance (choice of right data structure, algorithms, tools) and are difficult to change after the fact.
#4 Arguing about style isn't a good use of time. There has to be some measure of consistency/coherence in a code base but it's easy to take too far.
#7 There's a fine line between a best practice and a cargo cult. Don't do something just because it's a best practice. Do it because you understand the relationship between the practice, the circumstances, and the results.
#17 There's a positive side to personal attachment to the code. You care about it. Also did #34 just state the opposite?
#1 There's nothing wrong with TODO comments. Often you don't want implement feature B in full so that you can focus on feature A. Of course you've told your customers that you'll do both features, so you push feature B back to a future release. No problem in using TODO there - at least you have comments as to what's actually going on and what may need to be fleshed out in the future.
Normally the argument is the this should be part of your backlog and not spread all over the code where no one (and especially the PO) can keep track of all the TODOs in all the files.
Depends on trust. I've had an experience where old tickets documenting important architectural problems (e.g. SQL injection) were mass-closed as "probably obsolete" by managerial types.
I was very happy I left a TODO in the actual code calling out the problem, because I could find and reopen the wrongly-closed ticket.
I was very happy I left a TODO in the actual code calling out the problem, because I could find and reopen the wrongly-closed ticket.
Heh. Visual Studio actually does keep track of all the TODOs in all the files in your project. It's the Task List window (View -> Other Windows -> Task List, or ctrl-alt-K).
Does it track FIXMEs?
By default it looks for the tokens: HACK, TODO, UNDONE, and NOTE.
However, you can add your own tokens and assign different priorities to them.
https://docs.microsoft.com/en-us/visualstudio/ide/using-the-...
However, you can add your own tokens and assign different priorities to them.
https://docs.microsoft.com/en-us/visualstudio/ide/using-the-...
Very nice, it now almost resembles the functionality of "grep -rn FIXME ." in the shell and ":grep -r FIXME ." in vim.
[deleted]
[deleted]
>But after the fact optimization rarely happens, is more expensive and won't get you there. Don't do unnecessary optimization at the end of the project and don't them them in the beginning either. The necessary ones need to be thought out in advance (choice of right data structure, algorithms, tools)
The worst optimizations I've ever seen are pre-optimizations. I've seen many designs, in fact, that were attempting to prematurely optimize and inadvertently caused future performance problems.
The best optimizations, by contrast were done at the end of a project where the default was "keep the code clean", not "try to predict future performance issues".
The worst optimizations I've ever seen are pre-optimizations. I've seen many designs, in fact, that were attempting to prematurely optimize and inadvertently caused future performance problems.
The best optimizations, by contrast were done at the end of a project where the default was "keep the code clean", not "try to predict future performance issues".
It is often too obvious that e.g. O((x+y)^2)-drawing will degrade quickly. There is no point in implementing it slow way, because you'll see the effect in few hours and will spend few hours to fix all the places, not mentioning re-architecture cases. 100ms vs. 500ms is non-trivial to predict. O(log(n)) vs. O(n^3) for freely growing n is trivial.
The code that iterates over items and skips on condition isn't any easier to read or detect errors than access via bsearch or similar subroutine. In fact, straightforward code tends to introduce errors. Optimizations and correct naming [and thus centralized control] of routines are pretty close to each other, and when you give a name to get_cached_col_offset(col, last_known_col, last_known_offset) or have explicit caching iterator, the code looks much readable than for(y)-for(x)-everywhere mess with different off-by-ones and overflows in each block.
Where is that line separating dumb code from clean code?
Edit: wording
The code that iterates over items and skips on condition isn't any easier to read or detect errors than access via bsearch or similar subroutine. In fact, straightforward code tends to introduce errors. Optimizations and correct naming [and thus centralized control] of routines are pretty close to each other, and when you give a name to get_cached_col_offset(col, last_known_col, last_known_offset) or have explicit caching iterator, the code looks much readable than for(y)-for(x)-everywhere mess with different off-by-ones and overflows in each block.
Where is that line separating dumb code from clean code?
Edit: wording
For #17 I think he meant more that you shouldn't take code criticism personally. His pithy one liner summary just didn't capture the idea well.
"Join now" and inaccessible page.
Wait, what?