What is the benefit of short readable code if you only see functions and classes on the outside?

Question

Last years I made myself familiar with Python and Haskell. I am surprised and impressed about the short and readable code you can write in these 2 languages, especially in comparison to languages like Java, C++ and C#. Of course this is very motivating to pursue my journey in Haskell and Python.

However with languages like Java, C++ and C# most of the time you deal with code "from the outside". That is: you see the class together with its properties and methods, but how exactly the methods and properties were written you do not care about, as long as they do what they promise to do.

So I was wondering if it truly matters when code is short and readable and my enthusiasm about Python and Haskell is justified because there are lots of situations (in professional software development) were you see code only from the outside.

Now I know a lot of developers do not comment their code. In these cases you do benefit from short readable code. However as long there is the opportunity to document code I am not convinced.

Answer 1

how exactly the methods and properties were written you do not care about, as long as they do what they promise to do.

Exactly. But as soon as they don't do what they promise to do, you have to go check the code to see why aren't they doing it. Stepping in your colleague's code may reveal simple, clear, well-written code, in which case, you'll be happy. Or it will be a 4 000 LOC monster, in which case, you'll be... challenged.

This doesn't apply exclusively to the code you'll be potentially modifying. On several occasions, I had to dive into proprietary .NET Framework's code, because it wasn't behaving according to my expectations. In such cases, being able to see very well written code allowed me to understand within minutes that my expectations were flawed.

So I was wondering if it truly matters when code is short and readable

If the code will never be read by anybody, it doesn't matter. Therefore, if you're writing a script to automate a task, and you know that as soon as the task is performed, you'll throw the script, there is no reason to waste your time on code quality. Hack something as quickly as possible; if it works, it's great.

In most cases, however, code is read much more frequently than it's written, making it essential to write readable code.

Now I know a lot of developers do not comment their code. In these cases you do benefit from short readable code. However as long there is the opportunity to document code I am not convinced.

You may:

• Write a piece of unclear code which needs to be commented in order for someone to understand it. Chances are, the next guy who modifies the code will forget to modify the comment, which means that the comment will be outdated.

• Write a piece of unclear code, think about a better way to do it, and refactor it into a piece of clear code.

See also:

• What's wrong with comments that explain complex code?

• How can I deal with a team member who dislikes making comments in code?

Answer 2

First, separate the issue of short code from readable code. While brevity can contribute to readability, it doesn't guarantee it. Nor does it guarantee efficiency of execution.

So I was wondering if it truly matters when code is short and readable and my enthusiasm about Python and Haskell is justified because there are lots of situations (in professional software development) were you see code only from the outside.

Every developer wears two hats: a writer of code and a consumer of other programmer's code.

As a consumer of code, I don't care what language the code I import is written in, nor do I care what coding standards they enforce. I only care that I can call it from whatever language I'm working in, that the code meets my requirements, is correct, and is actively maintained.

However, as a writer of code, I've worked on projects that have had multiple releases over a period of decades. Thousands of other developers consume our code. One of the disciplines that makes this possible, is that my colleagues and I do care about whether our code is readable. Every day I have to revise code that I or someone else on my team wrote 7 years ago.

If you are writing throw away scripts that are used once and never touched again, you might think that readability is unimportant. You'd be wrong, because all but the most trivial scripts have to be debugged to get them working correctly. Debugging readable code is much easier than debugging obscure code.

As an example, if you use the SciPy package in Python you'll probably be calling functions that in turn call functions from Basic Linear Algebra Subprograms (BLAS), a library of matrix manipulation routines written in FORTRAN. As a user of SciPy, I really don't care what their readability standards are. But the folks who are responsible for maintaining BLAS have to care deeply how readable their code is, because they're the ones who have had to maintain that code for almost 40 years.

Now I know a lot of developers do not comment their code. In these cases you do benefit from short readable code. However as long there is the opportunity to document code I am not convinced.

Because inevitably the code and the comments will get out of synch, i.e. somebody will make a change to the code and neglect to update the comments. Then the future maintainers will have to figure out both the comments and the code, and figure out whether the comments, the code, or neither, is the correct version of what should be happening. I do use comments, and I try to be disciplined about updating them, but I assure you that even with the best of intentions, they will come to diverge. If your code isn't readable, sorting things out will be needlessly painful.

Answer 3

However with languages like Java, C++ and C# most of the time you deal with code "from the outside".

Most of the code I use, I deal with from the outside.

Most of the code I write, fix or refactor, I deal with from the inside.

Most of the code I use, I use in a split-second.

Most of the code I write, fix or refactor, I spend at least a few minutes on, and sometimes many hours.

So really, most of the time I deal with code from the inside, because while the code I'm dealing with from the inside is a minority of the code I'm in some way "dealing with" it's the code the vast majority of that "dealing with" is spent on.

Answer 4

I am assuming the code you write is going to be used by others.If so it will need to be maintaned and/or extended.Code readability and size are key parameters for achieving those desired properties such as maintanability and extensibility, and good practices such as code reuse when writing code.There are numerous benefits of writing maintanable and extensible code with the most prominent and important being ease of potential modifications and generally managing certain parts of it. It will only make your partener's and your life easier when the time comes for you to alter the implementation,structure, behaviour, and provide the option of adding new parts on it.

Of course there will be cases where you have to sacrifice readability for efficiency, but in most situations you should be able to find a sweet spot in between these two.

If on the other hand your code is a mess (huge and difficult to read) you'd have to spend too much time & effort in processes like debugging or refactoring , which I dont think is the most pleasant thing to be dealing with. There is a saying that I adore that goes like

"Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live. Code for readability."

Thinking open source also, it is a very good practice to write readable code, so others can understand, contribute and improve your software(in order to get the best out of it) and for you to be able to pick up new coding styles-practices from others.If code is self-explainatory you also eliminate the need of unnecessary documentation.

Even on the case where you simply want to use a particular piece of software("being on the outside"), it would be good for you to be able to track down the way it functions, in order to avoid unpredictable bahaviour, and choose what best fits your purpose if you have multiple options (e.g. libraries).

IMHO it is better to think harder and code simpler, because apart from writing better software it also helps you become better in the way you think and solve problems.

So i would ask you why not do it, if it makes your better as well as everyone else's life easier?