Best Advice on Writing Clean Code

[#1]

What’s the best advice you have for writing clean code?

Whether it’s keeping a copy of the Clean Code Cheat Sheet on your desk or regularly tackling coding challenges to keep your skills fresh, we want to know how you improve your coding skills.

The first 20 replies to this thread will be entered in a drawing for a $100 Amazon Gift Card.

[yatin]

Here are some points for writing clean code:-

1) Use meaningful names for variables.

2) Write good comments for each code block.

3) Single responsibility principle. i.e. one function should perform one functionality.

4) Independent architecture.

5) Remove unnecessary code.

6) Refactoring.

[alardt]

Great list Yatin.  After 20 years at the same company, I have to write knowing I'll possibly be looking at the code down the road.  It's easier to write it when you are also documenting it for your "future" self.

[joe]

The best way to write clean code is to have an open and feedback-heavy code review process. Otherwise will catch what you overlook.

- read the documentation, carefully (e.g. Effective Go - The Go Programming Language)

- use correct indentation and consistent code style. Does wonders for readability. 

- make variable and function naming clear, even if it makes the names long 

- comment heavily and in full English. 

[frank]

While this shouldn't be a difficult question to answer , the definition of "clean code" could mean different things to different programmers, organizations, reviewers,etc. I would be lying if I said here that all of the code I've written in my 20+ years of doing so would be considered "clean" (in fact, most of it isn't!! ). That said, however, I am "happy" with it, because I continue to learn something new on a daily basis - not just from exploring new techniques and innovations, but also when reflecting on the code I (and others at my company) have done in the past.

Aside from the excellent answers already provided, clean code, IMO, is code that one can learn from - if it's bad, then just knowing (and hopefully taking advantage of!!) opportunities exist to make it, and future code, better are a good thing. If it's good, then it can and should be used as a tool for teaching "green" developers that not everything they learned in school is applicable 100% of the time.

- GoF patterns are not features, kids!  Use them only if the need presents itself - while the new Abstract Factory you created may impress some of the junior developers around you, the likelihood that you needed an OSx and a Windows version of your CreditCardSale operation is probably very small

- Code should speak for itself (sorry joe‌ ) - while comments are useful, you shouldn't have to try so hard to explain what it's doing. Always apply the KISS principle, no matter how far away from Valentine's Day it is... 

- Love your QA people, and get them involved before you write a single line of code. Review your project's requirements with QA and any SME's to see what expectations they have from what you're about to embark on. Sometimes (speaking from experience here, folks) programmers will get ahead of themselves - perhaps from overconfidence - and just jump right in without knowing what the true intentions of the features are, or how someone without a programming background will be using what they will write. Remember, you're not using the software you are writing, so don't write it like you are  - your QA (PM/BA/etc.) is closer to the person that will use it most times. Knowing that will allow your code to be praised for its efficiency and effectiveness!!!

- Did you forget to write that unit test?  Shame on you... 

- Take breaks. Watch a cat video if that's your thing (I don't get it, myself, but hey...). Burnout really sucks and will have an impact on your personal life (trust me on this), not to mention the code that you write. I'll look back on some code I'd written when I was burning the candle at both ends (with the midnight oil, too!), and damn - it is far from clean. Had I given myself the time for my brain to relax and be nourished with proper rest, my code would have shown that.

- Be nice to the programmer whose code it is that you are reviewing - he/she will probably review yours someday (oh, did I mention? Have code reviews ). You may not "agree" with how another programmer has decided to do something, but perhaps they know something you don't, or have seen something you've overlooked. Try to learn something from others' code before being critical or judgmental...

[agates]

- DRY (do not repeat yourself)

- KISS (keep it simple) - don't write unnecessarily complicated stuff

- RTFM (read the docs)

- when fixing a bug make sure you fully understand the underlying problem before tackling it. Oftentimes you can create two new bugs while fixing one due to a lack of understanding.

- leave lots of comments where necessary. When I look back at code that looks wrong/weird and there's not a comment on it I kick myself - because I don't know if there was a reason I was doing that weird stuff.

- be smart when re-writing code. A lot of times code is messy because the problem is a lot messier than it seems on the surface.

- Also, personal preference - descriptive variable names. It can get wordy, and it's Java-like so it's not cool anymore, but if you know what type and what abilities a variable has when you're well past its definition, that makes things way more readable.

[tapank]

Adding on these very helpful comments above, a couple of things that help constantly improve my coding skills are: 

- Getting as much feedback as possible

- Accepting criticism

- Willingness to adapt and improve

Most of the fundamental coding practices are pretty much standard, however, coding styles vary between teams and it is upon oneself to adapt to it.

[chetansanghi]

1. Every day spent 15 min on learning or reading through best practices or clean code guidelines. It could be "Effective Java Programming" or "Clean Code" book.

2. More and more practice of TDD so as to make sure each line of code written is unit tested and there are no surprises.

3. Using online programming website like Hackerrank to keep yourself abreast of latest and greatest

4. Form a discussion group or more like a guild of developers and other team members in company and discuss and brainstorm problem on hand

5. Do more and more code review for others as it helps see lot of mistakes or ideas which are otherwise missed

6. Use of Findbugs, SonarQube on regular basis to keep improving

7. Reading of data structures, algorithm and design pattern and more importantly practicing it and implementing in code.

8. Use of SOLID and DRY as much as possible.

[thegreatcreativ]

1. First figure out why? Having an understanding of the project gives a direction. 

2. Then choose your language, HTML, CSS, XML, SQL, PHP, JQuery, and other Web technologies in addition to JavaScript. Give variables and methods purposeful names.

3. Keep a consistent coding style.

4. Review code with other coders that understand "clean coding"

5. Test. and repeat to keep the "clean code" mindset.

[kuno]

I'm still maintaining code I wrote 25 years ago. I'm glad I inserted lots of comments. I was particularly careful to make notes in complex sections where there was lots of handling exceptions. Using clear descriptive names for fields, variables, methods and objects helps a lot too. Most important of all is the user interface. Novice users should be able to look at a a screen and have a good idea of what is going on. Always provide a help button that immediately pops up a window clearly explaining what is happening on that specific screen and what the options are. Never make the user search for help and your support phone won't ring so much.