Some people mentioned they thought the code was messy. Casey addressed that on the stream of day 45 (at 32:30). Essentially, he said that the code we write is to understand how we want to structure the program, and so that "cleaning it up" would be premature "optimization" (wasting time). He also said that "clean code" means:
- easy to find bugs in
- easy to read and understand
- easy to reuse (in the places where it actually needs to be reused)
And also that the "cleanness" of the code should be evaluated according to those objectives, and not to a set of fixed principles.
I couldn't agree more. However, there is a change which I feel would be beneficial: more comments.
Being in Europe, I always watch the YouTube videos. But before, I pull the new code and commit it to a local git repository. Then I look at the code changes that are going to be introduced to get a sense of what is going to be done. Sometimes I can tell what the purpose of the changes is, but very often, I can't.
Similarly, when we revisit or expand on old code, I very often can't remember what it did, and reading it only gives limited insight.
A few terse comments stating the intent of some sections of the code would help immensely. Likewise, a few comment explaining some variables could help as well.
Comments like this (making things up):
I feel it's also justified since Handmade Hero is a learning project. Comments serve as reminders and help with understanding.
You probably wouldn't do this (in throw-away code!) if you are coding a game on your own. It does make sense in a team however, if it would take more time for your teammates to figure stuff out (or to ask you) than it takes you to write the explanation.
Let me know what you guys (Casey and fellow viewers) think!
- easy to find bugs in
- easy to read and understand
- easy to reuse (in the places where it actually needs to be reused)
And also that the "cleanness" of the code should be evaluated according to those objectives, and not to a set of fixed principles.
I couldn't agree more. However, there is a change which I feel would be beneficial: more comments.
Being in Europe, I always watch the YouTube videos. But before, I pull the new code and commit it to a local git repository. Then I look at the code changes that are going to be introduced to get a sense of what is going to be done. Sometimes I can tell what the purpose of the changes is, but very often, I can't.
Similarly, when we revisit or expand on old code, I very often can't remember what it did, and reading it only gives limited insight.
A few terse comments stating the intent of some sections of the code would help immensely. Likewise, a few comment explaining some variables could help as well.
Comments like this (making things up):
1 2 3 | // Compute the distance between the player and the obstacle using Pythagoras' theorem // dPlayerP will hold the delta between the old and new player position |
I feel it's also justified since Handmade Hero is a learning project. Comments serve as reminders and help with understanding.
You probably wouldn't do this (in throw-away code!) if you are coding a game on your own. It does make sense in a team however, if it would take more time for your teammates to figure stuff out (or to ask you) than it takes you to write the explanation.
Let me know what you guys (Casey and fellow viewers) think!
I like to make a bad analogy.
Messy code is actually caused by three things:
1. The passion of organizing things.
2. Temptation of wishing to see things that are short and concise.
3. Leaning towards disliking to remember abstractions and concepts.
If you have a thought in your mind saying, "This is messy code.", it may be a sign of you wanting to organize the layout structure of the code in a way that only you may like, whether or not the code will run successfully after restructuring the layout.
Messy code is actually caused by three things:
1. The passion of organizing things.
2. Temptation of wishing to see things that are short and concise.
3. Leaning towards disliking to remember abstractions and concepts.
If you have a thought in your mind saying, "This is messy code.", it may be a sign of you wanting to organize the layout structure of the code in a way that only you may like, whether or not the code will run successfully after restructuring the layout.
I think Casey puts LOTS of comments in the stream, and he uses also very long and descriptive names for his code. So taken together, I don't think more comments in the code would help much. But you need to view the stream. This takes time, that many maybe don't have. But far as I can tell, if you need it, it's worth it.
asperatology: I think that's sometimes true, but you can't generalize that to dismiss all readability arguments. By the way, you're badly misusing the word "analogy".
Kladdehelvete: I watch the stream, I just don't watch it live.
There isn't lots of comments by any possible stretch of the imagination. Most comments are TODO, or notes to record why some things are not done in the obvious way. It is also simply not true that a lot of time is spent on these. These comments are necessary, but adding comments to highlight intent would help. It wouldn't take much time to add these either.
You want to see well commented code? Look at another educational project, the MINIX operating system. Here are the old style guidelines:
http://wiki.minix3.org/doku.php?id=developersguide:codingstyle
And here is what it gives in practice (I just picked a file at random):
https://github.com/minix3/minix/blob/master/minix/fs/ext2/balloc.c
Now, I am **not** advocating this level of comment for prototype code. But a few terse comments to explain what we are doing would go a long way.
Kladdehelvete: I watch the stream, I just don't watch it live.
There isn't lots of comments by any possible stretch of the imagination. Most comments are TODO, or notes to record why some things are not done in the obvious way. It is also simply not true that a lot of time is spent on these. These comments are necessary, but adding comments to highlight intent would help. It wouldn't take much time to add these either.
You want to see well commented code? Look at another educational project, the MINIX operating system. Here are the old style guidelines:
http://wiki.minix3.org/doku.php?id=developersguide:codingstyle
And here is what it gives in practice (I just picked a file at random):
https://github.com/minix3/minix/blob/master/minix/fs/ext2/balloc.c
Now, I am **not** advocating this level of comment for prototype code. But a few terse comments to explain what we are doing would go a long way.
I actually think the code is too verbose! IMO, its easier to read code using much shorter names for local variables. The function names are ok. Regardless, it's still easy to work with, and as long as it's consistent and understandable it doesn't really matter what style is used.
Casey has mentioned it's not worth commenting the current code since almost all of it will be revised - comments get out of sync very quickly when you're doing explorative code. Eg We have seen quite a number of TODO's in the code that were stale.
Old comments that don't reflect what the code is doing is worse than having no comments at all.
Casey has mentioned it's not worth commenting the current code since almost all of it will be revised - comments get out of sync very quickly when you're doing explorative code. Eg We have seen quite a number of TODO's in the code that were stale.
Old comments that don't reflect what the code is doing is worse than having no comments at all.
I think many of those comments are actually pretty terrible comments. The comments that tell you the why are the useful ones. When your comment simply states what your code is going to do, not only is it unhelpful, it's potentially very dangerous. These are the types of comments that seldom get updated and don't actually reflect the code.
Writing good code is like writing a good term or thesis paper. You start by flushing out your ideas and penciling in the big areas you want to cover. Then you start revising and pulling in better data points. You'll also start restructuring your content so that it flows better and is more cohesive. All along the way you are keeping track of your notes and summaries of sections so that you can provide a good abstract and a good reference index.
In the end, you have a cohesive unit that creates a full picture. Some places get more polish then others because they are more important to the outcome. However, if you look at all of the intermediate steps in the middle, it will look like a giant mess.
Writing good code is like writing a good term or thesis paper. You start by flushing out your ideas and penciling in the big areas you want to cover. Then you start revising and pulling in better data points. You'll also start restructuring your content so that it flows better and is more cohesive. All along the way you are keeping track of your notes and summaries of sections so that you can provide a good abstract and a good reference index.
In the end, you have a cohesive unit that creates a full picture. Some places get more polish then others because they are more important to the outcome. However, if you look at all of the intermediate steps in the middle, it will look like a giant mess.
I kind of like his Notes and TODO because we I can tell between what type of comment it is and what to do and I don't find his comment very bad at all.
In the book, Code Complete it mentions a whole argument about commenting. One argument was "There's no point in commenting about what a code does if the code already shows what it does". This makes sense but then again, somebody who is scrolling though the code fast and don't want to read the code can see what they are doing. There two sides to this and it's hard to come to an agreement on how to comment because everyone has their own way.
For me, writing out his comments was a lot of work, in addition to trying to follow without the source code, pausing and unpausing on youtube and maxing (to see better) and restoring the screen. It's prob better if I had two monitors.
In the book, Code Complete it mentions a whole argument about commenting. One argument was "There's no point in commenting about what a code does if the code already shows what it does". This makes sense but then again, somebody who is scrolling though the code fast and don't want to read the code can see what they are doing. There two sides to this and it's hard to come to an agreement on how to comment because everyone has their own way.
For me, writing out his comments was a lot of work, in addition to trying to follow without the source code, pausing and unpausing on youtube and maxing (to see better) and restoring the screen. It's prob better if I had two monitors.
C0D3
I This makes sense but then again, somebody who is scrolling though the code fast and don't want to read the code can see what they are doing. There two sides to this and it's hard to come to an agreement on how to comment because everyone has their own way.
The day the compiler validates my comments with the surrounding code is the day I will believe the comment is correct. I've worked on too many shared code bases with too many different types of coders to ever believe a comment is true and accurate.
owensd
The day the compiler validates my comments with the surrounding code is the day I will believe the comment is correct. I've worked on too many shared code bases with too many different types of coders to ever believe a comment is true and accurate.
That is exactly my feeling, and the reason why I don't comment code until it's done. If you comment code that is in progress, it is almost guaranteed to be wrong by the time someone else might actually be able to read it and benefit from it, since you will forget to correct all the comments when you make changes.
We already see this happen on Handmade Hero with the TODOs. Those are OK because they are just markers to remind me to do things, so it's OK if we look at them and then go "nope, that was already done." But if those were instructional comments? It would be totally misleading to people all the time. It's probably already bad that there are TODOs that suggest something isn't done yet when it is, but, TODOs are too important for me not to use them.
- Casey
I guess the difference is that you don't always implement a TODO in the place where the TODO is written.
If you change commented code, the comment is just besides the code. If you go very fast, you can still miss it and the compiler won't warn you. So it does require a bit of discipline. According to me it's worth it. In my own coding this actually keeps me honest wrt what I'm doing and prevents me from doing some coding mistakes when I work on tricky code.
About comments giving the why, I do agree. That's what "intent" means, it means explaining why we are doing what we are doing. Not everyone can pattern match math formulas for instance, so having their name or their purpose stated up front is helpful. So far it's relatively manageable, but I feel it won't always be so.
If you change commented code, the comment is just besides the code. If you go very fast, you can still miss it and the compiler won't warn you. So it does require a bit of discipline. According to me it's worth it. In my own coding this actually keeps me honest wrt what I'm doing and prevents me from doing some coding mistakes when I work on tricky code.
About comments giving the why, I do agree. That's what "intent" means, it means explaining why we are doing what we are doing. Not everyone can pattern match math formulas for instance, so having their name or their purpose stated up front is helpful. So far it's relatively manageable, but I feel it won't always be so.
Edited by norswap
on