Some people assume that their code is readable enough so that they do not have to write comments. While sometimes that may be true, sometimes it is not. What I would have given just so that the programmer would write a comment on what the function actually does so that I do not have to actually read the whole thing. I mean, if I had to read the code line by line, what happened to abstraction of code? Isn't that supposed to make programming easier by keeping me from having to care about how you implemented you function, just as long as I know what it does, what it needs (as parameters) and what it returns?
If the code is small, fine. Perhaps that is something forgivable because I would have time to know the code completely. But what if the project is around 50-100 files of source code long?
There are some programmers who even inadvertently just copy and paste the code, which means that sometimes they include code that is not used at all. Even if redundant code does not have anything to do with documentation, if someone had taken the time to document the code, then someone would have noticed that the function is quite useless in the context of the program, no?
Anyway, it has become my policy to at least explain at the top of my files what the code inside it really is. I tell them that this only includes the class prototype, and heck, I even put what the class does. Some people just write classes and they end up with misnomers that confuse the heck out of me.
If you write bad code, it is a given that I will dislike you. But if you write bad code AND even not have the courtesy of documentation, I will dislike you even more. Giving someone else badly written code and making them read it is just like writing a badly written story or essay and expect someone else to appreciate it.
So, kids, make sure that you write your code properly, and more importantly, never assume that the next person who will be working with your code has the time to read through your implementation. Write some comments: Explain it to them. Keep it clear and concise.
Hope you guys continue enjoying writing code.
2 comments:
lol, i hope i put enough documentation in my OJT project.. :O
// yay comment XD
Hello Tin!
Perhaps a short description of what the code does in general might help.
In my OJT the code that I worked on also had comments for each of the functions, so that you know what that function does even without thinking too much about it.
Post a Comment