Scripting Helpers is winding down operations and is now read-only. More info→
Ad
Log in to vote
2

When and how often should I be commenting in my scripts? [closed]

Asked by 6 years ago

When I was first learning how to code everyone said that it was crucial that I comment on different areas of my code so that when I came back I would know what it did. Also someone mentioned that I should be putting my name and everything at the top of the script so that the credit for writing it would go to me. Now I really have not been commenting at all except as a note to my future self to change something. Could someone explain to me proper commenting rules and format as well as what to say. Hope someone can help me. Thanks!

4
Commenting is your own discretion. When you're starting off learning to script, it may be seen as a good idea so you can learn what you're actually doing with the code. Some people use comments for instructions for other people to use their code (such as script settings). Generally it's just for note of future reference. M39a9am3R 3210 — 6y

Locked by User#19524

This question has been locked to preserve its current state and prevent spam and unwanted comments and answers.

Why was this question closed?

2 answers

Log in to vote
7
Answered by
fredfishy 833 Moderation Voter
6 years ago

It really depends, and honestly it's just sort of something you have to learn for yourself.

As ScriptGuider already mentioned, lots of comments everywhere is generally a bad thing. Code should be largely "self-documenting", which is basically a fancy way of saying that somebody should be able to work out what your code is doing from the code alone.

Again, this is sort of something you just need to get a feel for with practice, but there are a few pitfalls people commonly fall in to.

1) Don't write too many comments

Writing too many comments is often considered a code smell for several pretty good reasons.

1a) You aren't a better programmer if you can write more stuff in fewer lines

A common trap for a lot of people when they start out programming is that they assume that being able to write their entire program on a single line is a good thing. It isn't.

Let's take some code using Python's list comprehensions as an example. Which is better code?

for customer in enumerate(customers):
    for product in customer.orders:
        product.decrement_stock_count()

versus

[[w.decrement_stock_count() for w in v.orders] for v in customers]

While both of those are the same, which is quicker and easier to understand? While you can't abuse list comprehensions in Lua in the same way, there are still shortcuts some people like to take, which you should be wary of.

As Linus Torvalds, creator of Linux puts it

if your typing speed is the main issue when you're coding, you're doing something seriously wrong

While code golf can be great fun, to make code readable again it generally requires a hideous level of documentation through comments. Once you start writing more comment than code, it's time to take a step back and ask yourself why you hate the people in the future who have to read your code so much.

1b) Name variables, functions, etc, properly

Now look. I know when you wrote it, the variable names i, j and k were perfectly clear in your head. I get that. Everybody's written code like this at one point or another. It's usually something you get past pretty quick.

Similarly, a function name of "do_the_business" may be fine when you can keep it in your short term memory long enough to use it, but when you come back in a week's time because you've been working on other sections of the codebase, you're going to hate your past self.

Function names should be descriptive enough that you can tell what they do at a glance. Identifier/variable names should be descriptive enough that you can tell how they're used at a glance.

In a related vein, if you ever have a function taking more than three arguments, make sure you consider how clear it is when it's called what all those different arguments actually do.

-- What are 3, 5 and 7?
function buildMap(3, 5, 7)
    -- Do the business
end

-- Use a string as an enum rather than an integer to select map type
-- Pretty obvious that 3 and 5 are the map's dimensions, and "rocky" is the type of map
function buildMapWithDimensions(3, 5, "rocky")
    -- Do the business
end

In most object oriented environments, this is a little easier, because you can encapsulate code in objects much more easily. It's still something to be aware of in an environment like ROBLOX though.

2) Think of providing multiple "levels" of comments

We've talked about inline comments, but what a lot of people don't consider are the levels above. Specifically in this case, function-level and script-level comments.

A good function-level comment describes how to use the function, what it does, what needs to be true for the function to execute successfully (pre-condition) and what will be true after it has executed successfully (post-condition). This is especially important if you're writing some sort of library for other people to use, but is useful when applied elsewhere.

Sort of linking back to a previous point, function-level comments should also describe what the arguments a function takes are (e.g., their type, what each one means, etc., but do not use this as a substitute for naming your arguments properly), and if it returns anything, what it returns. This may also include optional failure states.

For example, if you write a general purpose function to find an element in a list with a binary search, it might be useful to define a failure state for if the element isn't present, such as returning an index value of 0 or -1.

Similarly, script-level comments should describe what a script does as a whole, and a general overview of logic flow through the script.

0
Thanks! User#21908 42 — 6y
Ad
Log in to vote
5
Answered by 6 years ago

In addition to M39a9am3R's comment, you should aim to write code that minimizes the need for comments like...

-- do this
-- this does that
-- check if ... is true

Of course, this all depends on the purpose of the comment or the context in which the comment was written in. Writing code to reduce the use of these kinds of comments just results in cleaner, more readable code.

0
Thank you I gave you an upvote. User#21908 42 — 6y