How Do You Ensure Your Code Speaks Clearly to Other Developers?

Change focus for the next 3 days. If I come back after 3 days and I don't understand what is going on, then it is poorly written. Few years ago I couldn't believe the saying that I will read code 90% of the time and write code 10% of the time... Right now, I read so much code that I forget where I started...

First, I think it is important to set up some ground rules within the team you are working in. These rules start with the file structure and have impact the whole way throughout how we write an if-statement (in Java, if it is a one-liner, do we implemented with or without curly brackets?). The benefits I see with this are:

• You are faster at coding because the little details have already been taken care of
• The code looks uniform also to a new developer
• Code reviews are easier because the new code does not feel like a completly new code basis

Second are code reviews or even pair programming. You can barely assess wether the code is readable for someone else if your are not that other person and for reading over it yourself after a couple days we often lack the time. So, just get a second opinion while the code is still fresh at least in your mind!

And of course - Clear naming of things, yet this of course is often easier said than done! 😅

In general, I try and keep my comments professional, name my variables properly, and have a general formula for spacing and such.

For example, I try and describe each subroutine of a function, instead of the just the function itself. I find this a lot easier to read, and much more scalable on larger projects.

Another thing that I've been reminded of while reading the comments under this post is variable names. In general, I just try and stay descriptive and clean, but I've gotten a lot of my ideas from this video.

I also mentioned my "general formula" for spacing, and I'd like to expand on that. I find it helpful to have a standard spacing for subroutines/sections, functions, and classes. I normally do 1 space between subroutines and sections, 2 for functions, and 3 for classes (the only exception being if any of these are at the top of a class/function). Let me put this all together for you:

#just a test class, no real purpose ATM
class Test:
     #test function, returns nothing
     def test_func(a):
            #variables
            user_input = a
            iteration_count = 4

            #print the users input "iteration_count" number of times
           for i in range(iteration_count):
                 print(user_input)


       #just another test function, returns nothing
       def another_test_func():
             pass

Finally, as a lot of other people are saying, I definitely like the "come back later" strategy". If you can't understand what you wrote after reading the code a few minutes, a few hours, or a few days later, your buddy probably can't understand it.

• Define the preferred layout of your code and use a code-beautifier to enforce it.
• Use a linter to find extra issues in the code and fix them.
• Use meaningful variable names and functions names, but don't waste too much time on it. Instead regularly refactor the code improving the names when you think about a better name.
• Write short functions. If a function gets too long split it into two or more.
• Write tests!

Wrote a blog post around same thoughts.

dev.to/stud2design/code-aesthetics...