Posts Tagged ‘code comments’
JLPT list progress
Word definitions checked:
7260 (of 8626)
Comments
Coco Creme on zkanji v0.1.0 (beta) | |
Pearlene Agliam on Qt user interface design diffi… | |
zkanji on zkanji v0.1.0 (beta) | |
zkanji on zkanji v0.1.0 (beta) | |
Mystearica on zkanji v0.1.0 (beta) | |
Mystearica on zkanji v0.1.0 (beta) |
Categories
- Bugs (8)
- Development (40)
- JLPT (8)
- N3 list (6)
- Notices (5)
- Other projects (4)
- Plans (25)
- Polls (2)
- Program features (11)
- Progress report (8)
- Rant (30)
- Releases (17)
- Site (2)
- Study links (1)
- Test releases (10)
- Uncategorized (19)
- Under-the-hood (11)
- Updates (1)
backup
C#
changes
changes in JMDict
cheating
code
code comments
concept
containers
data export
data files
data import
data structures
delay
design changes
dictionary
emulation
example sentences
export file
how to study
human behavior
images
installer
interface design
interface translation
JavaScript
JLPT
JMDict
kanji information window
kanji recognition
kanji test
languages
layouts
long-term study list
memory usage
name
open-source
optimization
popup windows
programming
public domain
Qt
STL
stroke order diagram
threads
TTS
ui
uninstaller
updates
user data
user interface
version number
vocabulary
WaKan
website
what's missing
Windows 7
Wine
word filters
word groups
word test
Past entries
Pick a day
M | T | W | T | F | S | S |
---|---|---|---|---|---|---|
1 | 2 | |||||
3 | 4 | 5 | 6 | 7 | 8 | 9 |
10 | 11 | 12 | 13 | 14 | 15 | 16 |
17 | 18 | 19 | 20 | 21 | 22 | 23 |
24 | 25 | 26 | 27 | 28 | 29 | 30 |
Necessity of writing comments in code
I’m working on the handwritten kanji character recognition. At least that part doesn’t need reworking, I thought. Maybe it doesn’t, though I plan to improve on it a bit. What gives me headaches (apart from the fast changing weather) is that I don’t really understand a lot of the code now.
As I’m working on the new version, I try to describe what each part of the code does, so I’m adding comments everywhere. In the original code there was almost none. I could easily understand what the program does, so why add any? Good code explains itself? I have seen that line a lot before. Unfortunately it’s only true about code which solves a very simple, easy to understand problem with a simple algorithm. NOT for handwritten kanji character recognition.
I can’t make much out of the old code without considerable effort doing so. Because of this, even copying the old code takes a lot of time. Not that I’m just copying it either. I’m not sure whether all of my old decisions made sense or not, but regardless of that I would probably make different ones now. It’d be good if someone reading that code (even if it’s me years from now) could figure out why those decisions were made.
I think I’ve learned my lesson, but that doesn’t mean every single line will get commented either. Some parts really do explain themselves. Others might not be obvious to everyone, but as I was solving the same problems the same way years back, they will be easy to read in the future too. I have seen code before which had more comments than code, and it was hard to read because of that. If the algorithm is complicated, explaining it in a few long paragraphs at the start of the code is better than writing a description about each line.
Just to clarify, I’m writing this because it helps me concentrate while I code. I doubt anyone will change their habits because of this blog.