Comment your Code!

/, HTML, JavaScript, jQuery, PHP/Comment your Code!

Comment your Code!

Sure we are all self proclaimed guru’s our code is our kingdom, why should we take notes. We made it we can read it. Well all I can say to that is your logic is flawed. Just cause you write code today into next week does not mean in a month from now after writing 1,000+ lines of code else where your going to remember whats what, when or where.. or even why. Now you have to go back into your own code and either append to it, take away from it, or whatever to enhance it. Be it cause of a new exploit thats out, or some function got went legacy and you just upgraded your code language version.

\r\n

Whatever the case, eventually you will come back to your code, and when you do I don’t care who you are. The two key problems you will be faced, that will have you scratching your head for hours is, one the inability to remember what you did and why, two as your grow as a coder your coding style changes, you learn new things, new techniques, etc. I can’t count the times I’ve gone back to code I did several years back and said to myself “What the hell was I thinking?!?”. But in both events and likely several others your going to be faced with having to reverse engineer your own code. Which is funny cause you think messing with other peoples code is a royal pain in the you know what, cause you didn’t write it. Now here you are facing your old self. Worse off you left yourself no notes to work with.

\r\n

So we come back to Comment your Code! Im not saying leave yourself a book per function, per if-else, per whatever. Just do at the very least the basics. At the beginging or end of your functions leave a small less than 50-70 char message about the function (cause thatReallyCoolName()) you gave it won’t make sense, and your going to want some context to why you made it in the first place. Also try to comment at the end of your if, if-else/if-else at the very end closing bracket ie “//this closes this == that”. Also like at the top of your functions where you leave a short synopsis (unless a book is needed). Do the same at the very beginning of your if statements (likely within the first opening bracket) again serving as a small synopsis as to why this was needed.

\r\n

Commenting your code is helpful in so many ways not only for your own time and sanity saving purposes, but lets say you build this completely awesome site/service and someone comes a long and says hey I wanna pay you 1,000,000 for your site/service lock-stock-barrel (domain, code base, rights). Giving the keys over to the site will be a much smoother transaction if your code is commented cause you wont have to spend as much time training people who to develop around your coding style. It also says to the buyer its a good investment cause now I dont have to spend extra money on 3 extra developers to figure out this heap (All of which usually will have you on retainer as a consultant til everyone is comfortable). Commented code means less learning curve, less learning curve means you can get out and enjoy that $1,000,000 quicker.

\r\n

But back to reality, not everyone is going to build a site/service that will be such a success. Nor will they likely only stick to one site/service. Example (maybe a bad one) but I own several domains and sites (which currently are not up or running for various reasons). But from this the point is that going back between various sites and services doing various different things the logic, concept, etc is different for each site/service. Without commenting I would spend more time reverse engineering what I did just to move forward an inch rather than with commenting just view my notes and jump into development making huge strides as needed in less time.

\r\n

Anyway, this article may seem random at best, and in some cases with my code may seem like I am being a hypocrite but. I say this to all those up and coming developers who are eventually looking to make big things happen, or want a job in the industry where they will be working in a collaboration of efforts (another reason why commenting is good). Or what ever the case. Sure taking a moment here and there to stop coding and do something less enticing sucks, but the pay off is very good. Personally and I think most can agree once you get in the habit you don’t realize that your just doing it. But in doing it, everyone’s happy in the end yourself included.

\r\n

Just for reference what to you would be easier to read in time (use your imagination and pretend these examples have hundreds of lines of code between each opening and closing bracket.

\r\n\r\nNo Commenting:
\r\n
\r\nif($this == $that)\r\n{\r\n   if($me == $you)\r\n   {\r\n   }\r\n   elseif($me == $them)\r\n   {\r\n      if($here !== $there)\r\n      {\r\n      }\r\n   }\r\n   else\r\n   {\r\n   }\r\n}\r\nelse\r\n{\r\n   if($something == $nothing)\r\n   {\r\n   }\r\n}\r\n
\r\n

\r\nCommenting:
\r\n
\r\n//Need to make sure that the user is sole user and not part of many\r\n//blah blah comment comment comment blah..\r\nif($this == $that)\r\n{\r\n   if($me == $you)\r\n   {\r\n      //this is going to check to see if I am me, but flagged as you\r\n   }\r\n   elseif($me == $them)\r\n   {\r\n      if($here !== $there)\r\n      {\r\n      }//end here != there\r\n   }\r\n   else\r\n   {\r\n       //I am not you or them so I dunno whats going on\r\n       //error out.\r\n   }//end me = you\r\n}\r\nelse\r\n{\r\n   if($something == $nothing)\r\n   {\r\n   }//end something = nothing\r\n}//end if this = that\r\n
\r\n\r\nOf course this is also handy in CSS, and other languages HTML for example laying out a template? I could have for example with my HTML5 Blank Starter put a html comment at the end of each div so I know where one begins and one ends container wise example\r\n
\r\n\r\n
\r\nimagine more code here\r\n
\r\n
\r\n\r\nOf course if I am using a server side language and I want to keep my comments out of the view source from the public I could also do commenting in that language php is my flavor so Ill use that..\r\n\r\n
\r\n\r\n
\r\nimagine more code here\r\n
\r\n
\r\n
By |2014-01-05T10:17:30+00:00September 5th, 2012|Code, HTML, JavaScript, jQuery, PHP|0 Comments

About the Author:

Not much to know about me, I'm a 35+ year old coder, geek, gamer..

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: