Code Ethics

One thing that I've learnt from past few weeks is the importance of code readability and some other fairly useful fundamentals.

The widely ignored factor whilst coding a program is readability. Code is for humans afterall. The Code should be pleasing to read not a burden. There's no point in having concise code if people don't understand it, particularly when working with multiple people (which is the case most of the time)

Motive after code?

The primary motive behind your code is to compile successfully but what you've been told is wrong apparently. Believe me anyone can write code that a computer understand, writing code that humans can understand is the way to go. Code that is unreadable by other engineers even if it functions, is bad code.
If the computer doesn't run it, it's broken. If people can't read it, it will be broken. Soon.
You'd really want to write good code now No? There is no accurate definition of good code although there are some constraints that will possibly help in writing good code to some extent

But how?

Self-documenting code

What I mean by Self-documenting code -- thou should use techniques such as clear and und'rstandable variable names

Example - Instead of n or count, it is better to use a readable self-explanatory name such as blog.numberOfWords. That is a minimalist's documentation. Not only for variable names whether of modules, objects or programs even for function arguments, should be encouraged. The code must always have a clear and clean structure so that a human reader can easily understand it.

Choosing variable names is more of an art. Ask yourself if someone were looking at the name for the first time what would they make of it? Will they understand its purpose?

“Master programmers think of systems as stories to be told rather than programs to be written”
— Uncle Bob.

Always try to use Pronounceable names -- If you can't pronounce it there will be difficulty in discussing the code with your fellows

What is it that we achieve with self documenting code?

  • Minimize use of comments
  • Source code easier to read and understand
  • Minimized effort required to maintain the code

But what about comments?

For inline-comments, they don't make sense to me most of the time
  

    sentences[i] = sentences[i] + "." // Add fullstop to ith element of sentences
Such comments often get further truncated or lost as the code began to grow. If you're going to write a comment, give it at least a full line or better, give it more space as you need but as I've mentioned self-documenting code does not fully eliminate comments from your source code but minimize their use. Again, I'm not saying you should not comment, just keep in mind that in self-documenting you don't have to explain every line in comments.

Code splitting

Making code split in parts can help reader to focus on only what is relevant to them. Here we can mind our good friend Abstraction. It makes the code really maintainable and readable you'll see in the example.
The essence of abstractions is preserving information that is relevant in a given context, and forgetting information that is irrelevant in that context.
Let's take some example, here the method doSomeComplexCalculations() is abstracted from our main file. This code might look simple but by splitting the method doSomeComplexCalculations we are making the code future-safe, confusion-safe and bug-safe. Let me elaborate how.
        

  from renderer import doSomeComplexCalculations
  def renderSomeStuff():
    # Some lines
    doSomeComplexCalculations("test")
    # More lines
Now suppose someone wants to make a change in #Some lines(say), they just don't want to huge see the huge chunk of code which is inside our method doSomeComplexCalculations because it's really irrelevant to them in this case. Seeing it might cause confusion or maybe scare them :p who knows! we don't have slightest idea who'd deal with the code in future.

Following these methodologies will definitely help you code better I think.

This is not an end. I will try to write about more ways to clean the code!

At last thank you for reading this and if you have any kind of feedback feel free to hit on this anonymous Feedback link.