writing mantainable code

[martov]

Im working on my fist "big" programming proyect and I am trying to make the code as readable as possible, since reading someone else's code (or my code 6 months from now )is a huge challenge for me.

I have tried heavily commenting everything, but im starting to feel that the code is getting messy due to so many comments everywhere and it's actually getting harder to read so Im starting to question myself what would be the best way to keep it simpler and easy to read

http://s28.postimg.org/lncvuh6gr/Sin_t_tulo.jpg
how do you guys do it? is there some tool that helps with this? (makes a graph of the flow of the code or something to make it less painfull to read)

[micha]

Here is a random collections of ideas, taken from my experience and from some great sources (see below):

• You read your code more often than you write it. Usually you write each line once, but then later read it five times or more. Therefore it is a good idea to spend a little more time while writing such that the reading is easier later.
• Take some time to find good variable names/function names. I find this very difficult, but it pays out. I you find good names, then the code does not need comments.
• If you have a function and cannot find a good name for it, because it does too many things, then split it into many smaller functions.
• While you are programming, always prioritize readability over performance or code length. It's better to have seven very readable lines of code and two extra local variables than having two unreadable lines of code with no extra variables. If your code becomes to slow then, you can optimize it later. Don't write unnecessarily complicated code, only because you believe, that it might be faster that way.

Here are the great sources, that I learned these lessons from:
Small functions are good for the world by Kikito
Indie your face: Clean code
Indie your face: Clean code pt2: 10 more advice

[kclanc]

I comment a lot, but I try to write comments that are not redundant. This is not an absolute rule, but I think that most comments which occur inside of function definitions are fairly redundant. For example, consider the following code.

Code: Select all

--assign face to image containing face
local face = love.graphics.newImage("face.png")

If the reader of the code knows what the newImage function does, and knows what a lua assignment is (which is a reasonable assumption), having the comment is pointless. On the other hand, comments which explain the various parameters of a function are not redundant at all, because figuring the roles of those parameters out can be non-trivial.

I tend to comment at the function level of granularity, and my comments always specify what a function does rather than how it goes about doing it; in other words, I comment my intentions and interfaces, not my algorithms. I think that for code to be readable, someone should be able to understand a function implementation without having to read through the code of each of the functions it calls out to; interface comments are essential for this.

On another note, I think that placing assertions at the top of one's functions in order to verify assumptions about the arguments being passed into the functions are extremely helpful for maintainability.

[Plu]

As a general rule I tend to keep my comments in the spirit of this (dunno who said it first, or best, but the gist works)

A comment should never explain what the code does, it should explain why it does it like that.

That is to say; you should place a comment when you made some sort of design decision in your code that isn't immediately obvious just from reading it. The code itself should be fairly obvious in terms of "what is going on here", so use your comments to fill in the gaps.

For example, bad comment:

Code: Select all

function calculateValue( in )
  if in < 5 then -- if in is smaller then 5, just return it
    return in
  end
  return calculateComplicatedValue( in )
end

Good comment:

Code: Select all

function calculateValue( in )
  -- most calls are small numbers, for which output equals input
  -- since this gets called A LOT and the calculation is expensive, don't calculate it unless you have to.
  if in < 5 then 
    return in
  end
  return calculateComplicatedValue( in )
end

[OttoRobba]

I see you have quite a few files already but I'm always in favour of breaking your code into even smaller files (even if it means more files). I tend to do it like this:

Code: Select all

--modules/obj_manager.lua
local activeInstances = require "modules/instances"

--rest of code

Code: Select all

--modules/instances.lua
return {
show = function(id)
--whatever module code you want
end

}

You can then freely call any functions of the activeInstances table and whatnot.

Code: Select all

--modules/obj_manager.lua
local activeInstances = require "modules/instances"

test = activeInstances.show(id)
--rest of code

As far as comments go, I seldom use them but when I do, it is like headers, like this:

Code: Select all

--player.lua

self = {}
self.hp = 100
self.mana = 100

------------------------------------------------
-- Player Health
------------------------------------------------
self.addHp = function(num)
   self.hp = self.hp + num
end

return self

I feel it helps sometimes. But in general, I simply avoid large files. I used to have one that was 400 lines of code, it was getting hard to manage it. I broke it into multiple files and now it is 220 lines long - and I'm working on shrinking it further.

Another thing is syntax highlighting - ZB's standard syntax coloring is fine but you might benefit from testing other color schemes. Monokai, Zenburn, etc... all come preinstalled in ZB and, at least for me, make reading code much easier.

[kclanc]

I didn't notice the screenshot you posted. I like the comments describing the tables and functions that you declare. In my opinion, those comments in no way hamper the readability of your program. The comments that you have inside the one expanded function do not seem quite as helpful, as they contain information that I could have just as easily obtained by reading the code.

[murks]

I tend to write very few comments. I try to write easy to understand code and use comments only to explain stuff that is not obvious from the code, similar to what Plu does.

The reason is simple: if you write comments for every line of code an make a code change then you also have to change the comments. You not only have to maintain the code but also the comments. This tends to go wrong sooner or later. Programmers tend to change the code and forget about changing the comments. Then you end up with comments that say something different from what the code does and things get really confusing.

[martov]

thanks everyone, I will try to implement all this.