code commenting topic #1080
code commenting topic #1080
Conversation
There was a problem hiding this comment.
Overall this is good, but it needs some polish:
-
We don't actually need to separate things out into the "projects" and "topics" directories. It used to be required because of an ooooold version of the code. Now that is technical debt. Rather try to make things cohesive.
-
The project isn't linked to from anywhere so nobody will ever do the project or topic. Please make sure it is included in the right syllabuses.
-
It's a good idea to have a project here, but I think the project could be a lot better. It would be good to have multiple code samples and it would be good to cater to learners who work in different languages. If you need help coming up with code samples in different languages then come up with what you can and then reach out to the team to help fill in the gaps.
-
The topic looks good but I think people are not likely to absorb it. It would be good to have some code samples, even pseudocode would be ok I think.
|
|
||
| Understanding the difference between good comments and bad comments is essential for effective code communication and collaboration. Good comments provide purposeful explanations, relevant information, and clarity, while avoiding redundancy and outdated content. By following these principles, developers can create comments that enhance code comprehension, facilitate maintenance, and promote a positive coding environment. | ||
|
|
||
| #### Comment Evaluation |
There was a problem hiding this comment.
heading levels should not be random. This should be a level 2 heading.
| 4. Excessive or Unnecessary Comments: A bad comment includes excessive or unnecessary explanations that only add noise to the code. Comments should be used sparingly, focusing on areas that genuinely require clarification or insight. | ||
|
|
||
| 5. Sarcasm, Insults, or Personal Opinions: A bad comment contains sarcasm, insults, or personal opinions that are unprofessional and create a negative work environment. Comments should maintain a respectful and collaborative tone. | ||
|
|
There was a problem hiding this comment.
Maybe add a section on common problems. Eg new programmers often:
- just paraphrase code in their comments. Eg:
sum = 0 // initialise the sum variable to 0 - leave out comments completely because people keep telling them to stop making useless comments
It might also be useful to talk about who the comments are for. Comments are for coders - if someone who already knows how to code reads a comment then it should make their life easier somehow.
There was a problem hiding this comment.
It would also be good to mention something about self-documenting code.
Good code makes it's intentions clear. It does this by:
- using clear algorithms
- using well chosen names
- comments as needed
A common problem is something like this:
// calculate the temperature in fereignheit given the temperature in celcius
functrion calculate(temp){
return ....
}
If the code was just better then the comment wouldn't be needed at all.
There was a problem hiding this comment.
Generally, it's good to include examples instead of just explanations. It makes it easier for people to grasp what you are talking about.
| --- | ||
|
|
||
| ## Understanding Effective Comments in Coding | ||
|
|
There was a problem hiding this comment.
Heading levels are weird. Why are there 2 level 2 headings in a row? The "Understanding Effective Comments in Coding" section is empty.
Maybe the title should say "Understanding Effective Comments in Coding"
|
|
||
| #### Comment Evaluation | ||
|
|
||
| Instructions: Read the following code snippets and evaluate the comments provided. Determine whether each comment is a good comment or a bad comment. Answer the questions below. |
There was a problem hiding this comment.
Headings are very strange actually. I would rather do this:
title: Code comment evaluation
---
## Introduction
Why is the heading in the paragraph?
|
|
||
| ``` | ||
|
|
||
| 1.Evaluate the comment: "Function to calculate the area of a rectangle." |
There was a problem hiding this comment.
This is also weirdly formatted.
Why are there list items inside the numbered list?
Instead of asking them if comments are good or bad, it would be good to ask the learners to rewrite the code in a better way. The learners can be allowed to change the names of variables and functions if they want to. And it would be good to have different examples for different languages since not everyone does Python.
Eg:
Here are some code examples, please rewrite the code in a clearer way. Please make sure you only make use of comments that are actually useful. You are welcome to change function and variable names.
...
There was a problem hiding this comment.
- Heading levels are still not ideal. From the way the content is structured, all headings from the topic to the project should be level 2.
## intro
## another thing
## conclusion
This following makes more sense since the other headings are not sub-headings of the intro
- Regarding Sheena's comment about having "other languages" represented, I think she only means on the project. Also the other languages should be the ones we cover(python, js and java). I think python should be just fine on the topic though, no need to add csharp or other language syntax for beginners who may not be farmilliar
- I also think the other points in the topic need examples, it may be pseudocode or actual code snippets. Let me know if you need help with the examples for the other points.
| # - numbers: A list of integers | ||
| # Returns: | ||
| # - The sum of all integers in the list | ||
| function calculate_sum(numbers): |
There was a problem hiding this comment.
this example mixes js and python
|
|
||
| Understanding the difference between good comments and bad comments is essential for effective code communication and collaboration. Good comments provide purposeful explanations, relevant information, and clarity, while avoiding redundancy and outdated content. By following these principles, developers can create comments that enhance code comprehension, facilitate maintenance, and promote a positive coding environment. | ||
|
|
||
| ### Comment Evaluation |
There was a problem hiding this comment.
This should be a level 2 heading
| let length = 5; | ||
| let width = 10; | ||
| let result = areaOfRectangle(length, width); |
There was a problem hiding this comment.
This is telling the learners a lot about when to wite comments. I think that what is likely to happen is: Learners will add a whole lot of unhelpful comments to their code.
There's a more important lesson that is worth getting across.
Good code makes itself clear. It does so by making use of clear and consistent naming and clean algorithms. Comments are used when necessary and should focus primarily on WHY a piece of code is there rather than the specifics.
Comments are there to add clarification so that the people reading the comments have an easier time reading the code.
function areaOfTriangle(sideLength1,sideLength2,sideLength3){...
Adding a comment that says that this is a function that calculates the area of a triangle given the lengths of the three sides is not going to add any clarity. The code is self-documenting. Try to find out more about self-documenting code, it's a big deal!
Some documentation systems make use of comments in code and so if you are using certain tools then it can make sense to add redundant comments to functions.
But most of the time it's best to first aim for clear code and then add comments on the hard to understand parts.
The other thing that learners get wrong:
- junior coders think that writing fancy code means that they are fancy people
- senior coders know that writing clear code is the best thing
I think this is a good start. But I'm not sure if you are the right guy to finish this off, there are a bunch of examples in here that might actrually teach the learners to waste time.
Please fix up what you can and then when this comes back to me I'll polish it off.
| - any_language | ||
| prerequisites: | ||
| hard: | ||
| - /code_comments/introduction-to-code-commenting |
There was a problem hiding this comment.
why is there a forward slash here?
|
|
||
| 4.In your own words, explain why maintaining up-to-date comments is important in code development. | ||
|
|
||
| Please complete the Comment Evaluation project on a Google Doc. Once you have completed the project, ensure that the sharing permissions of the document allow anyone on the internet to view the file. Then, submit a link to the document by sharing it with us. |
There was a problem hiding this comment.
Rather follow the standard set out by the other writing assignments. It's explained in your other task, let me know if it doesn't make sense.
Basically we need people to submit repos. We dont want to protect the main branch. We do want them to submit 1 markdown file per question.
| Python: | ||
|
|
||
| ```python | ||
| def area_of_rectangle(length, width): |
There was a problem hiding this comment.
This code looks very clear to me... I'm not sure what the learner is meant to do here.
Maybe a better thing would be to include some code examples with really excessive commenting and then ask the learner to clean it up.
eg:
a = 1 // assign the value 1 to the variable named a
c = a + b // add a to b
eg2:
# get the area of the triangle. a,b and c are the lehngths of the sides
def area_of_triangle(a,b,c):
s = .... # semiperimeter
return ....
There was a problem hiding this comment.
The examples above are things I have seen learners do a lot.
What other problems do learners often have? Let's focus in on those problems.
I am sure you have given people feedback about bad commenting before? How can you give the learners those lessons in this project?
| console.log("Area of the rectangle:", result); | ||
| ``` | ||
|
|
||
| 2.In your own words, explain what makes a good comment. |
There was a problem hiding this comment.
I'm not sure if this will get formatted well. Should there not be a space? You have 2.In but it should be 2. In
| - Purposeful Explanation: A good comment serves the purpose of explaining complex logic, algorithms, or business rules. It provides insights into the code's functionality and helps other developers understand the intentions behind certain decisions. | ||
|
|
||
| ```python | ||
| # Function to calculate the factorial of a number using recursion |
There was a problem hiding this comment.
There are a few things that are bad about this comment:
- It should be a docstring so that Python's help system picks it up.
- Overly fancy - generally speaking it's best to explain things in the simplest way possible. The goal is to be understood. The goal is not to try to look smart.
I actually see learners trying to look clever by using overly stiff language and big words a lot. This might be worth sharing with them: https://socialtriggers.com/the-big-problem-with-big-words-hint-they-make-you-look-stupid/
|
|
||
| ```python | ||
| # Function to calculate the sum of integers in a list | ||
| # Parameters: |
There was a problem hiding this comment.
this should also be a docstring.
|
|
||
| > In this example, the comment explains the purpose of the code, which is to calculate the total price of items in a shopping cart and apply a discount if the total price exceeds the spending limit. It clarifies the logic behind the code and provides insight into the discount calculation, which might not be immediately obvious from the code itself. The comment adds relevant information that helps other developers understand the intention and behaviour of the code segment. | ||
|
|
||
| - Updates with Code Changes: A good comment is maintained and updated alongside the code. If the code undergoes modifications, the corresponding comments should be reviewed and revised to ensure they accurately reflect the updated logic. |
There was a problem hiding this comment.
It would be worth mentioning:
If you add too many unnecessary comments then those comments would need to be maintained. So it's better to write self-documenting code as much as possible so that you need to maintain fewer comments.
|
|
||
| > In this example, the comment explains the purpose of the code, which is to calculate the total price of items in a shopping cart and apply a discount if the total price exceeds the spending limit. It clarifies the logic behind the code and provides insight into the discount calculation, which might not be immediately obvious from the code itself. The comment adds relevant information that helps other developers understand the intention and behaviour of the code segment. | ||
|
|
||
| - Updates with Code Changes: A good comment is maintained and updated alongside the code. If the code undergoes modifications, the corresponding comments should be reviewed and revised to ensure they accurately reflect the updated logic. |
There was a problem hiding this comment.
It would be worth mentioning:
If you add too many unnecessary comments then those comments would need to be maintained. So it's better to write self-documenting code as much as possible so that you need to maintain fewer comments.
| } | ||
|
|
||
| // Updated version of the function to handle negative inputs as well | ||
| // This approach now includes a base case for negative numbers |
There was a problem hiding this comment.
This doesn't seem very useful...
You threw away some of the information from the previous comment. Are you saying that the previous information was unnecessary? If it was unnecessary why was it there in the first place?
Imagine a programmer who wants to make use of this function. What information do they need in order to use the function? Put that in the comment.
It looks like the only thing they might need to know is that negative numbers aren't allkowed. The rest is pretty obvious just from reading this line: function factorialRecursive(n)
There was a problem hiding this comment.
This is telling the learners a lot about when to wite comments. I think that what is likely to happen is: Learners will add a whole lot of unhelpful comments to their code.
There's a more important lesson that is worth getting across.
Good code makes itself clear. It does so by making use of clear and consistent naming and clean algorithms. Comments are used when necessary and should focus primarily on WHY a piece of code is there rather than the specifics.
Comments are there to add clarification so that the people reading the comments have an easier time reading the code.
function areaOfTriangle(sideLength1,sideLength2,sideLength3){...
Adding a comment that says that this is a function that calculates the area of a triangle given the lengths of the three sides is not going to add any clarity. The code is self-documenting. Try to find out more about self-documenting code, it's a big deal!
Some documentation systems make use of comments in code and so if you are using certain tools then it can make sense to add redundant comments to functions.
But most of the time it's best to first aim for clear code and then add comments on the hard to understand parts.
The other thing that learners get wrong:
- junior coders think that writing fancy code means that they are fancy people
- senior coders know that writing clear code is the best thing
I think this is a good start. But I'm not sure if you are the right guy to finish this off, there are a bunch of examples in here that might actrually teach the learners to waste time.
Please fix up what you can and then when this comes back to me I'll polish it off.
Related issues: [please specify]
Description:
What are you up to? Fill us in :)
I solemnly swear that: