New to Overclock.net
Join Date: Jun 2018
Location: Hendersonville, NC
Self-documenting code.. I like that term!
Even still - it doesn't hurt to put a comment above a function to explain what it does - also with programming I see too many people over complicate things. They write functions 10,000 lines long and then they end up repeating code 10, 20 times... Instead of that, make yourself building blocks. Simplify things - and I personally don't like to repeat code if I can help it. I turn repetitions into helper functions / building-blocks with a very clear purpose and use those throughout.
I also translate awkward functions - for instance... drawRect( x, y, x2, y2 ) is much more readable using ( x, y, w, h ) and the math becomes a lot less repetitive, less clunky and easier to read.
So there is a lot you can do to reduce the number of comments required to explain your code such as properly using Enumeration, Constants, variable naming, function / class naming, simplifying your code, making building blocks, not repeating code which could be a function, etc..
Also, by reducing the repetition - if that code chunk has an error, you only need to fix it in 1 place instead of every place used - but for this to work the function must be very clear.. For instance, say math.abs had an error where it did |x|+1 or whatever... Imagine having to snake through code to find all of those that shouldn't be there vs those that should... So we know what absolute value does, so if we see math.abs( x ) + 1 then we can see that it looks intended.
Anyway - if you have a strong coding standard and you apply it to everything, eventually you don't need to worry about it no matter how large or small the project is. And, as you become more familiar with coding standards used by other businesses, you can easily adapt if you change jobs. Ensuring the code looks like it was written by a single person or a very well orchestrated team who are all on the same page makes the code a lot easier to maintain because you don't have to discern between different styles making you wonder what to use in each segment of code you're working on, and so on. And, by making it easier, it saves the company money and gives them more of a reason to hold on to you. If the company doesn't have a system like this and you bring it to them, I'm sure they'd be grateful. If I knew nothing of coding and I was told it would save money because less time would be spent trying to figure out what person a does vs person b - I'd be all for it. In a business sense, some may not be - if the code or system is old and there is no major benefit right away, some people may just say leave it, or establish a coding standard, distribute it, and as you work on the code convert the things you work on until it is fully converted - or when you aren't busy on something else.