Please Read: Comment your code well!

Place for questions and answers for all newcomers and new coders. This is a free for all forum, no question is too stupid and to noob.

Re: Please Read: Comment your code well!

Postby Jackolantern » Wed Sep 04, 2013 10:18 am

Hamilton wrote:And just to be Captain Obvious:
Remove all comments from the files that will go live.


Remove all comments from files that will be transmitted to the user ;) For anything staying on the server (such as the file I copied above), it really doesn't matter, as pretty much every modern web development execution environment (PHP, V8, .NET, JVM, etc.) don't even import the comments for execution. Best to just leave them in so you don't accidentally lose the commented version.

For Javascript, the reason you want to strip out comments from the live version is for bandwidth reasons. But you really have two choices with JS: 1. minify the whole JS file to make it take up as little bandwidth as possible, which will automatically remove all comments among other space-saving mechanics, or 2. leave the code unminified and leave in all comments so other users can view the source to learn how you did something. There is really no reason to do anything in between those two. :cool:
The indelible lord of tl;dr
User avatar
Jackolantern
 
Posts: 10893
Joined: Wed Jul 01, 2009 6:00 pm
Location: Houston, TX
Has thanked: 22 times
Been thanked: 92 times
Blog: View Blog (1)

Re: Please Read: Comment your code well!

Postby hallsofvallhalla » Wed Sep 04, 2013 11:48 am

hmm i always though people meant commit your code, no wonder my code is a mess :P



Note: I am kidding
User avatar
hallsofvallhalla
Site Admin
 
Posts: 11998
Images: 13
Joined: Wed Apr 22, 2009 6:29 pm
Location: mobile, al
Has thanked: 11 times
Been thanked: 164 times
Blog: View Blog (3)

Re: Please Read: Comment your code well!

Postby Hamilton » Wed Sep 04, 2013 1:25 pm

Jackolantern wrote:There is really no reason to do anything in between those two. :cool:

There is one more reason, which is more with the field I have worked in (security). Granted this is not easy nor ethical, but has been done. And that is, to not make your work easier for someone else to reverse engineer (after acquiring through other-than-legal-means). If on the paranoid side, then add in some fake code (misdirect), as well as simplify the code, such as replace variable/constant names with letters (ie: PlayerStatStrength to ps). Make the live files hard to figure out (even if compiled), while the development files are as you said.
Sign off,
Hamilton
User avatar
Hamilton
 
Posts: 114
Joined: Tue Sep 11, 2012 2:11 am
Location: Here and There
Has thanked: 0 time
Been thanked: 0 time

Re: Please Read: Comment your code well!

Postby Jackolantern » Wed Sep 04, 2013 3:50 pm

Hamilton wrote:
Jackolantern wrote:There is really no reason to do anything in between those two. :cool:

There is one more reason, which is more with the field I have worked in (security). Granted this is not easy nor ethical, but has been done. And that is, to not make your work easier for someone else to reverse engineer (after acquiring through other-than-legal-means). If on the paranoid side, then add in some fake code (misdirect), as well as simplify the code, such as replace variable/constant names with letters (ie: PlayerStatStrength to ps). Make the live files hard to figure out (even if compiled), while the development files are as you said.


JS file minification will make your JS code as hard as possible to reverse-engineer, and will replace variable and method names, etc. If trying to keep people from understanding your code is a goal, that is about the best you can do. Of course, you can't rely on that, even with all kinds of misdirects and more, because if the JS engine can read it, so can a committed user who puts in the time :cool:
The indelible lord of tl;dr
User avatar
Jackolantern
 
Posts: 10893
Joined: Wed Jul 01, 2009 6:00 pm
Location: Houston, TX
Has thanked: 22 times
Been thanked: 92 times
Blog: View Blog (1)

Re: Please Read: Comment your code well!

Postby Chris » Tue Nov 14, 2017 8:40 pm

Comments can sometimes be deceiving. Code will only ever do what it does. Comments can be a good thing, in a dynamically typed language it is good practice to write comments as the code isn't always quickly self explanatory. When you do use comments, make sure they are kept up to date with the code. I find the best comments are comments which help declare the type of an instance. Comments that describe what the code is doing, can sometimes be misleading.

None the less, writing comments using standardized patterns means you can create your documentation while you write your code, which saves a lot of time.
Fighting for peace is declaring war on war. If you want peace be peaceful.
User avatar
Chris
 
Posts: 1575
Joined: Wed Sep 30, 2009 2:22 pm
Has thanked: 4 times
Been thanked: 5 times
Blog: View Blog (2)

Re: Please Read: Comment your code well!

Postby Jackolantern » Tue Nov 14, 2017 9:17 pm

Honestly I groan when I look at my commenting back then. Now I would much more suggest commenting using one of the *Doc-style systems (like NDoc, JsDoc, etc.) where you can generate documentation from them (and some of the nicer IDEs like WebStorm can parse and use that data to offer better code hinting), and then only comment unintuitive code outside of that. I depend more on descriptive variable and method names to explain my code.

Of course I think if you are just starting out and are likely to paste blocks of your code into forums or Stack Overflow, it is probably a good idea to add enough comments to have an idea of what is going on if the code is taken out of context. At least add them at the time you are copying the code to get help with a problem.
The indelible lord of tl;dr
User avatar
Jackolantern
 
Posts: 10893
Joined: Wed Jul 01, 2009 6:00 pm
Location: Houston, TX
Has thanked: 22 times
Been thanked: 92 times
Blog: View Blog (1)

Re: Please Read: Comment your code well!

Postby Chromeozone » Wed Nov 15, 2017 3:33 pm

Nice 4 year necro.

Is this the real Chris? Because... it aint useful in the slightest having to click through every thread just for it to be...crap?
Image
Chromeozone
 
Posts: 294
Joined: Sat Apr 09, 2011 8:21 am
Location: England
Has thanked: 2 times
Been thanked: 2 times
Blog: View Blog (1)

Re: Please Read: Comment your code well!

Postby Jackolantern » Wed Nov 15, 2017 8:10 pm

Well, this is a sticky so technically they are never necros (although this really probably shouldn't be a sticky looking back on it; I had forgotten about this one).

But I am pretty sure it is him.
The indelible lord of tl;dr
User avatar
Jackolantern
 
Posts: 10893
Joined: Wed Jul 01, 2009 6:00 pm
Location: Houston, TX
Has thanked: 22 times
Been thanked: 92 times
Blog: View Blog (1)

Re: Please Read: Comment your code well!

Postby Chris » Tue Nov 28, 2017 5:16 pm

Chromeozone wrote:Nice 4 year necro.

Is this the real Chris? Because... it aint useful in the slightest having to click through every thread just for it to be...crap?

Counting time in years is like counting gas in volume. Time is not as procedural as you might anticipate, and gas can be compressed into smaller volumes.

What was crap about my post? Personally I found that quite constructive.

I would highly recommend reading this if you want to create good PHP code: http://docs.phpdoc.org/guides/docblocks.html

JavaScript documentation is not very standardized unfortunately.
Fighting for peace is declaring war on war. If you want peace be peaceful.
User avatar
Chris
 
Posts: 1575
Joined: Wed Sep 30, 2009 2:22 pm
Has thanked: 4 times
Been thanked: 5 times
Blog: View Blog (2)

Previous

Return to Beginner Help and Support

Who is online

Users browsing this forum: No registered users and 1 guest

cron

x