Code appearance, is it really important?

Started by
26 comments, last by Khatharr 9 years, 3 months ago
I want to know if it really matters at the end of the day, how your code looks like or how you wrote it.

For example, I made a program to a friend who laughed at me because I wrote this(Python):

Numbers = [1,2,3,4,5,6,7,8,9,0]
NumbersRandom = []
For i in range(5):
X = random.randint(0,9)
Numbersrandom.append(Numbers[X])
random.shuffle(Numbersrandom)
Print (Numbersrandom)


Instead of this:

Numbers = [1,2,3,4,5,6,7,8,9,0]
Numbersrandom = random.sample(Numbers,5)
Print (NumbersRandom)


Both programs print a list of five random numbers, so what do you think about it? Is it the big deal or not?
Advertisement

Yes, code appearance is important. Neater, more compact and well commented code is easier to understand.

This means if you share it with other team members or ask for help or even if you come back to it years later, it is quicker to get to grips with and there is less margin for misinterpretation.

Code appearance and cleanliness is one of the most important aspects of being a successful programmer.

Having the computer do what you want it to do is only half the battle, and in most cases is the easier task. Figuring out the most efficient way to express those actions, is where most of your time will lie. Its extremely important to be able to tame all the data and algorithms you are using into a coherent instruction set that wont collapse from its own bloat.

Efficiency isnt only about execution optimization, but also hugely about the optimization of the Development of that code. The best code is code that minimizes the amount of effort it takes to type, test, modify and debug.

As you can see from the 2 samples you posted, one has significantly more logic in it that you will need to mentally step through to understand how it works. Whereas the second one does the same operation, in a compressed fashion that makes it allot easier to grasp at a glance.

So basically, yes it is a very big deal. Although it might not seem to matter in such a trivial example, the ability to right clean, succinct code is not gained by writing any code that compiles and works, but rather by constantly aspiring to write clean and succinct code.

IMO if you are the only person who will ever view the code then I'd say write it however it suits YOU. If there is any chance at all it will be shared then you should try to make it as neat as possible I guess. It's like I don't use my best handwriting when I'm making notes because I can understand it just fine but if I have to present my notes then I'll type it up. Well commented code can help.

I want to know if it really matters at the of the day, how your code looks like or how you wrote it.

For example, I made a program to a friend who laughed at me because I wrote this(Python):

Numbers = [1,2,3,4,5,6,7,8,9,0]
NumbersRandom = []
For i in range(5):
X = random.randint(0,9)
Numbersrandom.append(Numbers[X])
random.shuffle(Numbersrandom)
Print (Numbersrandom)


Instead of this:

Numbers = [1,2,3,4,5,6,7,8,9,0]
Numbersrandom = random.sample(Numbers,5)
Print (NumbersRandom)


Both programs print a list of five random numbers, so what do you think about it? Is it the big deal or not?

for a small program, no its not a big deal

For larger programs however things like that will add up to alot of unnecessary complexity, more complexity increases the risk of new bugs being introduced in the code, makes new features harder to add and makes existing bugs difficult to find.

[size="1"]I don't suffer from insanity, I'm enjoying every minute of it.
The voices in my head may not be real, but they have some good ideas!

It's not just the appearance of the code that matters: the second example shows a clarity of thought when tackling the problem domain, the first feels more like a mental hit and miss approach (i.e. you started coding before you knew what you wanted to code).

It happens to everyone - sometimes you just can't see a clean solution to a problem. I often find just walking away from the computer for a few moments can help, or in more complex cases getting out a pen and paper and writing down what you want to achieve, be it in English or via a flow chart or similar.

IMO if you are the only person who will ever view the code then I'd say write it however it suits YOU. If there is any chance at all it will be shared then you should try to make it as neat as possible I guess. It's like I don't use my best handwriting when I'm making notes because I can understand it just fine but if I have to present my notes then I'll type it up. Well commented code can help.

While this is generally true, I've definitely come across code snippets from the past and was totally confused by my own code. So I think it's important for code that might be reused by anyone(including just yourself), to go ahead and make it somewhat clean. Though I've definitely written throwaway code that I've never touched again shortly after hitting the compile button too, so there is that. And I would definitely not spend inordinate amounts of time making code ultra clean unless it was going to be viewed by others repeatedly.

I got part way through the first one and stopped reading. I made it all the way through the second one and understood what it was supposed to do.

Yes, code appearance is important. Neater, more compact and well commented code is easier to understand.

This means if you share it with other team members or ask for help or even if you come back to it years later, it is quicker to get to grips with and there is less margin for misinterpretation.

The only time it's fine to not have pretty code is when you DON'T want other people to know what it does. Otherwise, be sure to keep it neat and tidy and use plenty of comments!

Good code is as simple as possible as it's purpose will allow. It should be clean, tidy, and most importantly has comments except in places except for where it should be quite obvious what a segment of code is trying to do. Code not only is a form of writing, but also a machine that needs to be easy to maintain and work on.

That a computer language even exists is testament to the benefits of clarity. We could all be doing punch cards or pure assembler programming if this aspect made no difference.

Some standouts:

  • Once you establish your style, stick with it.
  • Keep consistent tabs for each new lexical scope.
  • Organize headers / routines so public, protected, private, etc. functions appear in the same order.
  • When possible, keep functions relatively small -- no more than a page at a time. If I start to see spaghetti code I build hierarchy to replace strands of code. It's a good way to establish concepts and start to see patterns. Spaghetti code is hard to understand especially when you're constantly scrolling up and down within the same function.
  • Give descriptive names to your functions, variables, files, etc.

You'll eventually write some code that you may return to later. With a clean, consistent style you'll get to the source of your bug when you find things where you expect to see them.

This topic is closed to new replies.

Advertisement