Where should comments be added in code?

I don’t think so because it is not executed, instead it is just to provide further description of the code you wrote.

1 Like

thanks for clearing that up!

1 Like

A comment still has to be parsed over when the python file is compiled into byte code, so at this stage it will be slightly slower. However, once running the comments will have been stripped out so the byte code will be the same with and without the comment.

4 Likes

I feel you @array2644225241 : I’ve been stuck in a traditional advertising job for the last 5 years running in circles… I started changing my career path last summer and feel really good about the job perspectives available to coders. Good luck to you and keep learning!

2 Likes

Early Python examples infer that, regardless of context, we need a meaningfully, clearly defined variable, reference and/or an argument for the defined variable/commands to result in a meaningful expression. Comments may offer context, but are meaningless unless no question remains unanswered; for example, when given the instruction to cp, copy, the below block, terminal prints nothing (terminal output remains blank), which elicits some confusion from a keen observer.

  • #This variable will be used to count the number of times anyone tweets the word persnickety
  • persnickety_count = 0

It prints nothing because although the comment offers context, there are 0 cases of persnickety, so it adds nothing to our overall understanding, opening only more questions with it, like why are we counting persnickety, how do we access the data to count it, how is a count useful for our current project, and what is our current project.

Useful comments answer all open questions, but the context offered, if unrendered, is useless. Comments must be comprehensive and completely supplement the expression in a way that allows for our audience to fully understand it. CodeAcademy, in my limited experience of it thus far, poses problems forcing inference for a complete understanding.

Basically, we must carefully read between the lines for the whole lesson. Our example forces us, as a reader, to ask, if the comment, which may be used at our discretion, added anything at all to our insight. It did not in this instance. If I were a trainer working with inexperienced programmers, I might feel irked. Know your audience. Use your tools to help them get where you need everyone to be in order to tackle your mountain.

#knowyouraudience #strengthinnumbers #safetyinnumbers

4 Likes

Hello.
I am new to codeacademy (and python) even though I am not new to programming so I will give some useful hints for commenting.

Commenting often is seen by many programmers as a very time intensive and annoying work so (unfortunately) it happens a lot that comments are just left out.

My hint for all new programmers is, to get used to commenting and get the habit of commenting as good as possible.
Think about someone who has no idea of coding wanting to understand your code.
This will help you to work in teams later and to create programs, that are easier to bugfix later (and it will help you as well to bugfix and to understand what you wanted to do with the code later).

Example, I will take the one with the hitpoints in a bit more detailed example, copying the phyton syntax mentioned there):

# When hitpoint (hp) are below 5% and shilds are gone, self-destruct
# Because we do not know the hitpoints, we calculate by the percentage with maxhp (maximum hitpoints)
# Calculation is hitpoints/maximum hitpoints which is checked against 5% = 0.05
# To change the % of the threshold you need to change the number 0.05 with 1.00 being 100% and 0.01 being 1%
if hp/maxhp < 0.05 and shields == false:
   self_destruct()

For longer text it is also useful to add keywords or topics to the documentation to make it more readable.
Good documented text also helps to build a code snipped library, where you can later copy/paste or implement the library and call functions instead of rewriting them every time.
In the example above, this might be self explanatory, but if you e.g. later have a big calculation going over 20 lines or more for one simple “hit” or “death checker”, it is good to get used to explain exactly what the different variables do and which numbers have to be changed to change the result.

I recommend to get the habit of “extended” documentation early to safe frustration (and time) with troubleshooting or rewriting (or understanding) old code fragments.

5 Likes

comments should be added at the beginning like a heading to the performing code

1 Like

Hang on in there because for you since you are now in the right place here at Code-learning, and a way to reach new height in what we and you can do; can turn into the right path-way to you and whatever you may be dealing with on the way to a new Career. :sunglasses: :100:

1 Like

I’m as excited as you are.
It’s extraordinary.

Why should the comments be before the program and not after

1 Like

comment can be written anywhere in the start or at end. Its just writing before the program will save the reader from confusion and make it easier for him.

1 Like

They don’t need to be before the program, unless you’re referring to things like the module docstring which needs to be at the start of the module. Arguably you can stick a comment anywhere that doesn’t break existing syntax.

If you’re referring to whether a comment should before or after a small section of code to which the comment has relevance then before would be the standard. You’d want to describe the intention/purpose of the code just below the comment.

1 Like

I think comments can be used to break down different sections, allow anyone else that may be working on a project to have clear idea of what each module is supposed to do

Comments are used for the purpose of the developer to easily understand the key of and a proper understanding with flexibility.

1 Like

Also so other people beyond the author to understand the overall goal and logic behind the program

1 Like

I wish I could say the same for the Javascript sections. This stuff just goes over my head :frowning:

Thanks! I had made a comment in my notebook for the classes to “show my work as often as possible” based on the wording of the lesson. Very glad to have read this response to know better. :rofl:

for the first time, I thought that I should add more comment, so the other can understand faster. But, it was a mistake. Comment and code is documentation itself. They should be clear, short.

I will break it in 3 steps

  1. Computer reads every line, word, code of information and try to understand what type of data it is example word are read as strings, numbers as integer

  2. We need to know what hp stands for if it is a variable that means it hold a value or its a certain number lets say 100 represented by hp so when we call hp we mean 100, to do this just write
    hp = 100

  3. he probably has the calculated 5% of the principal or the original number let the calculation be represented by x then all the code above does is to check if hp(any number) is “>” 5 or equal shield then compare it to the calculated percentage which is x in order words that’s not the complete code haha!
    hope that helped

A docstring at the start of any function should suffice as it will describe the variables and the return. That is all the commenting needed if we’re working with functional code.

Furthermore, if the documentation (extra comments) does not appear in the help literature of the function, then it should not be there (embedded in the code). That is what the docstring is intended for.

Bottom line, put comments where they belong, in the help literature, namely the docstring that describes the function. Otherwise, just write the darn code without annotation.