An idea for smarter coding comments

I often write code quickly and refactor it as an on going process. I tend not to have a ‘written’ list of things that need ‘fixing’ and up until recently kept everything ‘in my head’ (a bonus of generally doing all the front-end development myelf).

I am currently working on an app for a client from Denmark wherein eventually the codebase will effectively ‘leave my hands’ to go to another developer to pull apart and integrate into their system.

Make that change

This time I thought I would start to actually write things down.

I could quite easily add a comment to my SCSS like this

height: 300px; // TODO: magic number to be removed

Starting all single line comments on code that needs to be fixed with the word TODO. I could then search through my project using Sublime Text (for example) and fix these things as and when before the other developers start cutting and slicing.

Make it easier

I quickly got to thinking. Perhaps I could make my comments a little smarter. Rather than using the word TODO I could use a word that’s more ‘semantic’ to what needs fixing, looking at or refactoring.

For example I could take the above code and do this

height: 300px; // @magic

This would allude to what the comment is for, is easy to search groups of the same thing by.

Of course this could get tricky the more and I may need to create a glossary file of what the single worded comments mean.

I’m sure you can tell by the style of my writing that this is just a little brain-dump of an idea. It's probably not a even new idea.

(subject to change before 9am tomorrow morning and beyond.)