Writing readable code

Okay, family. I have a confession to make. I'm that guy who writes the unreadable code. I'm trying to get better through rehabilitation, but I'm going to need support from you guys.

What are some of the conventions you follow to help make code more readable? I've Googled it, and yet there are articles that say "just do what the big companies say", but then I think of Hungarian notation. I've looked at some of the code written by GNU, but that's unreadable to me. The two things I wonder about the most is when to comment and variable/function/class naming.

I did read this article, but people seem to disagree: http://www.cplusplus.com/forum/articles/26440/

I'm a fan of the old Unix philosophies. Is there any convention from back then that still works today?
> I'm a fan of the old Unix philosophies. Is there any convention from back then that still works today?

These are still relevant: http://catb.org/~esr/writings/taoup/html/ch01s06.html#id2877610
closed account (48bpfSEw)
I think...

there are too many rules for writing readable code and even if you follow all these rules there will be a lot of people who will thinking your code is not readable...

the best way is to write first a book about the subject you are working on in your native language and use this documentation as comments.

In the IT there are only 3 steps of relevance:

input
calculation
output

and these are functions and they need data which has a structure. so use struct or class for the data.

that's all. what do you need more?

1
2
3
4
5
6

struct ParamInput { data...}
struct ParamOutput { data... }

void Function ( ParamInput, ParamOut )


Last edited on
I'm trying to get better through rehabilitation, but I'm going to need support from you guys.

BWAHAHAHAHA!!! Errr...wait, that isn't supportive.

Teasing aside, writing readable code isn't something you do right off. You are already on your way to getting better because you are actually seeking to get better. You'd be surprised at how many think their code is perfect and neglects readability. In my opinion, poor readability and poor commenting are the two major issues with code. Don't get me wrong, code that is complex for no other reason than being complex is also a problem, but that is a different discussion. Like I stated though, the simple fact that you are seeking to improve shows you are already ahead of the game so to speak.
Haha thanks, my post was meant to have a twist of humor. I love CatB. Is there any more advice you have for commenting? Indenting and brackets?

Ooh, and here's a good one. How to print out helpful error messages? What should an error message contain? I know that you shouldn't print errors if you can help it, but what if you absolutely must?
Last edited on
My 2 cents:

I think that consistency is more important than having a particular style.

Being able to adapt your coding style is important if you ever want to work on a group project. Unfortunately there are "professionals" who drift onto a project, enforce their own "superior" coding style wherever they see fit, and then drift off immensely pleased with themselves, saying "ahh, my work here is done" & leaving a mess for others to clean up. These are not positive role models...

Commenting. There are a disturbing number of people who write hundreds of lines of code without any comments whatsoever & when you ask them what the heck some convoluted bit of code does, they irritably reply "the code is self-documenting". No it's not. Unless it's a "hello world" program, it is never self-documenting. A few brief comments describing what you meant a block of code to do and/or why you are doing it can be immensely helpful to anyone else trying to understand and/or debug your code. I sometimes write the comments before I write the code, which can be useful when writing something that is too big to be completed in one sitting.

If you ever find yourself holding religiously to one particular coding style above all others, then just bear in mind that you are chanting the following verse:

Ash nazg durbatulûk, ash nazg gimbatul, ash nazg thrakatulûk, agh burzum-ishi krimpatul

Translate that into the common tongue & replace "Ring" with "Coding Style". Then recognize your boss' true form and that you are wielding one of the minor coding-styles of power. Finally, use your foresight to see that the necromancer is about to make you his *itch-king and that this is not a good thing.
Haha I see you're quite the geek.
@RealGiganitris

Hi, my 1 groat worth :+)

Apart from the excellent link JLBorges provided:

Perhaps you could do some rubber-duck debugging for your problem: Post some code which you think is really bad; tell us what you don't like about it.

I know that is small scale (there are lots of bigger issues like the interface for example), but it could be helpful nonetheless.

Perhaps one concept of understanding might be that code should be reasonably understandable by someone who has a decent grasp of science and mathematics. For example, if someone is doing something involving a lot of math, provide links to the documentation in the code as comments, paste formulae into comments, provide comments about what C++ functions do. Imagine looking at code which implements the math in chapter 5 of this document, without those things: http://www.icsm.gov.au/gda/gda-v_2.4.pdf It's all very well to translate code into a math formulae - but what does it mean, and why? Note that is all independent of the person reading the code having great ability and knowledge of C++, or their very high level of education. It would be embarrassing for whoever wrote the code, to have someone of great ability looking at it and thinking: what the? If they are having trouble how are the rest of us going to fare?

That part about why is important - there may be several ways of doing something - why is it being done this way? Someone else might have a better way.

I quite often post a link to one of Norm Gunderson 's excellent posts, which shows in a comical way how using meaningful names can make the code read like telling a story of what is happening : http://www.cplusplus.com/forum/lounge/176684/#msg872881 Again, that is small scale - but still helpful.

Regards :+)

Edit: I should say that obviously one doesn't want to go too far with this: don't turn the code into some kind of tutorial - just give the reader a reasonable chance of being able to comprehend it.
Last edited on
Thanks guys, that's really helpful.
Topic archived. No new replies allowed.