Real quick: This essay is mainly written for those who are not a software developer yet, or don't code as their principal source of income.

Hey guys, as you all may know (for those who don't, I'm going to explain it real quick here) I changed jobs, and now, I'm working for a bank in Brazil (I won't share it's name here as I'm not paid for advertising them). Coding is a side thing in my career there, I mainly work with investment analysis inside Excel (VBA) and other Microsoft applications. Investment things are very nice, but Excel sucks.

As I've seen there, lots of people from Investment Banking are using programming languages to get their work done faster and better than before, which is great, but the point is: Are those codes produced by non-software engineer people maintainable in a production scenario?

Software engineers who care about their code quality, make their code thinking of: error handling, data IO, test-driven development, code readability, code complexity and many other aspects that beginners and non-expert people.

Why should I f*****g care about software maintainability?

If your code will only be used by you for a task, you shouldn't care a lot for these, your code needs to solve your problem mainly, but when you are working with multiple people in the same project/field/area/department/whatever, you won't be the only one who will use what you are coding.

For maintainability purposes, Python, created two PEPs that should be followed as a good practice for software engineering. Those PEPs are:

• PEP 8 - Which states how a user should write code (mainly style guide)
• PEP 20 - import this; or mainly known as Zen of Python (this little text that is below here)

>>> import this
The Zen of Python, by Tim Peters

Beautiful is better than ugly.
Explicit is better than implicit.
Simple is better than complex.
Complex is better than complicated.
Flat is better than nested.
Sparse is better than dense.
Readability counts.
Special cases aren't special enough to break the rules.
Although practicality beats purity.
Errors should never pass silently.
Unless explicitly silenced.
In the face of ambiguity, refuse the temptation to guess.
There should be one-- and preferably only one --obvious way to do it.
Although that way may not be obvious at first unless you're Dutch.
Now is better than never.
Although never is often better than *right* now.
If the implementation is hard to explain, it's a bad idea.
If the implementation is easy to explain, it may be a good idea.
Namespaces are one honking great idea -- let's do more of those!

As shown above, the simplicity and readability counts when developing new software that will be used.

Imagine if you get into a company and there is no documentation about that code, no deploy instructions, no development setup, just the code there. Would you be able to pick it up and continue working where the other people left it? Probably not, we all need best practices for better code maintenance and developers on-boarding on new systems! Maintaining a big code base without good practices is like this meme:

The best coding practices are those who all developers in your team know and apply, as well as can be passed to new developers. Here are some use cases of best practices that may be useful:

• If well written comments (or docstrings) are helpful inside your code base and guide new developers to the maintenance, keep them and update those that need to be updated. Don't keep dull comments, such as:

# Example of a dull comment

a = 1 + 2 # this line adds 1 with 2 and saves to

# Example of a needed comment

def really_cool_function_that_sums_to_numbers(x, y):
    # This function sums X and Y and returns the result

If you need to comment multiple lines of your code to make it understandable, its a good time to think on how to improve it. Code should be readable and easily understandable (PEP 20 lesson here)

• Functions should do just a single function (sounds redundant, right?) as like Pure Functions (concept from functional programming that states functions that cannot cause side effects to global variables and other functions).

There are plenty of best practices and code styling guides to follow according to your language of choice. The main point of this text is: remember that other developers will maintain your code on a near future, and you will probably maintain it too and won't remember lots of things. Make your code simple so people understand it and continue your work.

Originally published on: Vmesel's blog