2

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.

  • Possible duplicate of Refactoring into lots of methods - is this considered clean or not? – gnat Jan 7 '18 at 22:19
  • 3
    The code you see from outside really doesn't matter. Its all about the code you write and maintain. – Timothy Truckle Jan 7 '18 at 22:20
  • 3
    @gnat disagree about the duplicate. This is question is something different. – Elmex80s Jan 7 '18 at 22:23
  • 2
    @Elmex80s: "but you work in projects with other people not?" That does not matter. My point is: there is two kinds of code: Code I only use and code I contribute to (extend or maintain). For Code I only use I don't care on readability, regardless who wrote it. For code I contribute to I really do care about readability and SOLID principles, may it be written by team members or someone else. – Timothy Truckle Jan 7 '18 at 22:38
  • 3
    If you're the one using the "black box", then no, it's not supposed to matter. If you're the one writing the "black box", then it matters a great deal. – Mark Benningfield Jan 8 '18 at 3:15
13

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:

  • 1
    I'd argue that even code that you throw away after a single use has to be readable. The only exception is if you can you can sit at a keyboard and punch out 100% correct code with zero defects without looking at the screen. In which case I'd consider you a living god. For the rest of us mere mortals the more times you have to revisit code, the more readable it has to be, and generally one off code is is not produced instantly. – Peter M Jan 8 '18 at 13:18
  • @PeterM Exactly. I think it's foolish to assume that a piece of code is "finished." Bugs always pop up, so you may as well set yourself up for success in tackling when they inevitably appear in the future – Alexander Jan 8 '18 at 18:35
8

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.

1

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.

1

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?

  • 1
    Everyone is assuming "big code" doesn't matter if you're external to the code. I think it very likely does matter; 4 KLOC subroutines almost certainly lack cohesion. Something this complicated is unlikely to have a cleanly defined interface. Its probably not been tested properly either. – Nick Keighley Jan 8 '18 at 12:13
  • I agree with you, and even on the case of being external to the code, when looking for available options/implementations for a specific purpose, you should be able to track down the way a particular piece of software functions in order to choose what's best for you. Aside from that, it is a good thing for code to be self-explainatory , eliminating the need of unnecessary documentation. – ichantz Jan 8 '18 at 12:36

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.