2024-comments-are-a-programmers-love-letters

[dujue55]

Add the first article : Comments are a programmer's love letters

[Ajorian]

I think the expression 'the secret language of code' is somehow misleading. On the other hand, the negative side of over-commented codes is not considered. Maybe you can talk about a good balance of using comments.

[evos96]

External feedback:

negative aspect(s) pointed out:
-It was not clear (3)
-The article was too technical (1)
-I lost interest midway (1)
-I didn't understand the purpose (3)
-The structure was confusing. (1)

positive aspect(s) pointed out:
-The information was easy to understand. (2)
-Good balance between technical depth and readability. (5)
-The structure is clear and easy to follow. (2)
-I understood the purpose (2)

Did the drawing help you to understand the meaning of the article?
yes (9)
no (4)

Did you notice any factual errors or inaccuracies in the article? If Yes, which part?
-No it was very easy to understand
-To my limited knowledge everything is up to code

Additional comments
-Nice
-The comment example during the text does not match the content of the text.

[carinaschrenk]

Internal Feedback Round 1B 14.11

Thoughts

• Comment is not in line with the context.
• Too long.

Ideas

[dujue55]

Based on the feedback, I made the following changes to the article:

1. Removed the comment example as it was irrelevant and redundant.
2. Added a discussion on balance in using comments.
3. Shortened the overall content.

[ParthS007]

Review Group 5 (Arita, Ivan, Parth)

The revision effectively balances clarity and purpose in discussing the use of comments.

[belle903]

Ideas and notes from the creative writing session today:

Ideas regarding examples to visualise also for non-CS people:

• sticky notes on the fridge
• notes on walls from ancestors
• sticky notes on coffee machine
  • "don't touch it"
  • "fill beans here”
    --> show comments as notes explaining what is in a class/method

General notes:

• remove love letter
• comments are not necessary clear and with care
  --> as comments are a necessary thing to add to your code, it does not really depend on "love" for another programmer.

Suggestions for the title - make it catchy with a concrete example to refer to in the article:
- "What does it do?” (like a comment for a method on what the method does)

[carinaschrenk]

As Discussed in the seminar today, here is a sample text for one of the ideas mentioned by Laura:

Do you know how your coffee machine works? Probably not. But you can still make coffee with it. You can even adjust the amount of water or the grind level.

Often, programmers use code without knowing how it works. How can they do this?
Because the person who wrote the code left comments, explaining what the different parts do.
You can imagine it like a coffee machine in your office where someone put sticky notes next to the important buttons, explaining for each button what it controls.
There might even be a sticky note that says: „Do NOT touch!"

[cloudflare-workers-and-pages]

Deploying tilics with    Cloudflare Pages

Latest commit:	25ac474
Status:	🚫  Build failed.

View logs