5

In order to avoid further cluttering of the question's comment section, I will elaborate here on my stance. At the same time I would like to invite the user in question and the community to provide their thoughts as well.

Situation

2 days ago this question was asked. As you can see from the revision history the code was cluttered with so many comments that half of all lines were just comments. I removed all the comments while also fixing the remaining issues.

In the comments I left a note that all these comments weren't necessary. He disagreed with me on that point after which I left a final comment referring to Meta if he wishes to discuss it (paraphrasing, refer to the original question for exact words).

Today a new question was posted and by the style of the comments I immediatly recognized it as the same user. I already fixed the question once and left feedback; I wasn't going to fix it again. For this reason I simply left a comment asking to remove the unnecessary code and comments while referring to the "describe the specific problem" guideline.

He disagreed with this again so in order to avoid further escalation I decided to talk this out on Meta instead.

My vision

Unnecessary comments

I believe the comments and non-relevant code (including getters) should be removed. These comments don't provide any extra information at all; here are a few examples:

  • getter method to return the boolean value of the variable
  • constructor for ojbects of type CO2FromWaste
  • main method
  • 15 lines describing the purpose of a class, the private variables, etc

Every two lines of code has one line of comments, that's just needless clutter. It doesn't help the question, it just makes it hard to read.

My issues with these comments is that it is hard to find the problematic code. You're essentially forcing us to comb through a bunch of lines for no reason, you could just as well take them out.

Your main issue is that you think it takes too much work. I removed the comments in your first question in just a few minutes, how hard can it be?

Concerning the getters: are they really necessary? They have no functionality, all they do is return the field that's on top. You're not providing the source code for an ArrayList either, why would you add that from a simple getter? Once again several lines of code that can be condensed to an actually relevant comment: // Appropriate getters.

Unclear problem description

Further along the line of the off-topic rule, there is this quote from a comment:

"your code sample should describe the specific problem." it does--very specifically, I have given the error message--when ran, it returns this error.

I have looked through the entire post and tried to unravel what it is you're saying but nowhere could I find an error message.

Granted, I didn't specify this in my initial comment. The only reason I'm bringing this up is because you did.

I tried to find out what the problem was but all I got was that you thought it was something to do with boolean statements.

What boolean statements?
What made you think this?

You say something about receiving 0 values before you added boolean statements, but you're not specifying what your current result this.

You also said all your methods are just returning 0 without specifying what methods and what you expect them to do instead.

Last but not least there's your opening sentence:

I have an issue taking the values which I've set in the ArrayList of objects I've created, and printing their values

  • What issue?
  • What list?

This is an extremely unclear question with a lot of (irrelevant) code.

Pitchforks

I hope this isn't too late yet but I wanted to state that I don't have a personal vendetta against you, as you seem to assume. I'm acting from what I belief to pure intentions to improve the quality of the site where I can. However if I fix someone's question once, I expect notes to be taken for improvement in future questions, otherwise it's just an uphill battle.

I'm not claiming to be universally right so I might very well be wrong, which is why I'm bringing it up here.

Maybe a flag for mod attention might have been appropriate but since this would only provide me with very limited feedback in the case I was wrong, I decided to opt for a Meta post instead.

I'd like to see opinions on the - in my eyes - overdose of comments and clutter code and - possibly - how I should approach this differently in the future.

closed as off-topic by Glorfindel, ale, Nathan Tuggy, Robert Longson, ChrisF Mar 13 '18 at 20:59

This question appears to be off-topic. The users who voted to close gave this specific reason:

  • "This question pertains only to a specific site in the Stack Exchange Network. Questions on Meta Stack Exchange should pertain to our network or software that drives it as a whole, within the guidelines defined in the help center. You should ask this question on the meta site where your concern originated." – Glorfindel, ale, Nathan Tuggy, Robert Longson, ChrisF
If this question can be reworded to fit the rules in the help center, please edit the question.

  • 12
    Meh. Just downvote and closevote it if you feel it's excessive (I would agree, but I won't vote on the question to avoid the Meta effect). It feels like way too much code either way. If it were a reasonably sized code example the comments wouldn't bother anybody – Pëkka Jan 8 '14 at 4:22
  • 5
    Send him over to Code Review when he has working code. We'll set him straight ;) – syb0rg Jan 8 '14 at 4:41
  • 2
    I was all set to disagree with you and say that comments can be extremely useful, but in this case the OP has not used even a single useful comment; "Start of main"! Whats with that!? – Richard Tingle Jan 8 '14 at 7:20
  • 1
    I'd argue your behavior up until this point has been inappropriate. Calling the user out so explicitly only comes across as bullying him into changing his code. Get over it, move on, downvote if you must, but don't harass our users. – DanteTheEgregore Jan 8 '14 at 16:51
  • Oh, that kind of comments. I thought this was a question about SE comments. This belongs on MSO, not MSE. – Monica Cellio Mar 13 '18 at 21:03
24

If there is a policy to be cited here, it is this:

  1. In any edit war, the OP gets preferential treatment.
  2. Editing other users' code in questions (including code comments) is strongly discouraged.

There's no standing policy that says question posters are required to edit out spurious comments or make their comments relevant, although there's certainly nothing irrelevant about these comments.

Where you see this:

/* *
 * This class instantiates CO2 Electricity Emission objects with five private instance variables.
 * It contains three mutator methods: one to calculate the average annual electricity bill, another
 * for average annual price of electricity, and the annual home CO2 emission from electricity.
 * Private instance variables include monthBillAverage, monthPriceAverage, annualCO2emission,
 * emissionFactor, and months
 *
 * @author A. Mackey
 * @version 01/04/13
 */
import java.util.ArrayList;                                    //import the ArrayList class
public class CO2fromElectricity
{
    //declaration of private instance variables
    private double monthBillAverage;                           //the average monthly electricity bill.
    private double monthPriceAverage;                          //the average monthly electricity price.
    private double annualCO2emission;                          //the average annual CO2 emission from electricity.
    private double emissionFactor;                             //the emission factor for CO2
    private double months;                                     //months over which the CO2 emissions are calculated

    /**
     * Default constructor to create an objectfrom the CO2FromElectricity class.
     */
    CO2fromElectricity()
    {
    }

    /**
     * A mutator method that calculates the average annual electricity bill.
     * @param monthlyBill-an Arraylist containing the monthly bills for home electricity use.
     * @return The average monthly electricity bill.
     */
    public double calcAverageBill(ArrayList<Double> monthlyBill)
    {
        monthBillAverage = 0;
        for(double billToken : monthlyBill)
        {
            monthBillAverage += billToken;
        }
        return monthBillAverage / monthlyBill.size();
    }

    /**
     * A mutator method that calculates the average annual price of electricity.
     * @param monthlyPrice-an Arraylist containing the monthly price of electricity per kilowatt-hour.
     * @return The average monthly price of electricity.
     */
    public double calcAveragePrice(ArrayList<Double> monthlyPrice)
    {
        monthPriceAverage = 0;
        for(double billToken : monthlyPrice)
        {
            monthPriceAverage += billToken;
        }
        return monthPriceAverage / monthlyPrice.size();
    }

    /**
     * A mutator method that calculates the annual home CO2 emission from electricity.
     * @param avgBill-The average monthly home electricity bill.
     * @param avgPrice-The average monthly price of home electricity.
     * @return The annual home CO2 emission from home electricity use.
     */
    public double calcElectricityCO2(double avgBill, double avgPrice)
    {
        emissionFactor = 1.37;
        months = 12;
        return annualCO2emission = avgBill / avgPrice * emissionFactor * months;
    }
}

I see this:

import java.util.ArrayList;
public class CO2fromElectricity
{
    private double monthBillAverage;
    private double monthPriceAverage;                          
    private double annualCO2emission;                          
    private double emissionFactor;                             
    private double months; 

    CO2fromElectricity()
    {
    }

    public double calcAverageBill(ArrayList<Double> monthlyBill)
    {
        monthBillAverage = 0;
        for(double billToken : monthlyBill)
        {
            monthBillAverage += billToken;
        }
        return monthBillAverage / monthlyBill.size();
    }

    public double calcAveragePrice(ArrayList<Double> monthlyPrice)
    {
        monthPriceAverage = 0;
        for(double billToken : monthlyPrice)
        {
            monthPriceAverage += billToken;
        }
        return monthPriceAverage / monthlyPrice.size();
    }

    public double calcElectricityCO2(double avgBill, double avgPrice)
    {
        emissionFactor = 1.37;
        months = 12;
        return annualCO2emission = avgBill / avgPrice * emissionFactor * months;
    }
}

... with a bit of noise in between each declaration. Really, it's not all that difficult to mentally filter out the comments.

Certainly, providing relevant comments helps people who might answer the question. For what it's worth, I've seen far worse questions than this.

  • Alright, it seems like most people are leaning towards this point of view. Maybe it's all in my head, but I have a hard time focusing on the code when there are so many comments surrounding it. I appreciate the feedback. – Jeroen Vannevel Jan 8 '14 at 5:26
  • 6
    Worth noting that fixing code in questions is a definite no-no, you almost always end up obfuscating whatever problem the person was actually having. – Tim Post Jan 8 '14 at 5:26
  • Hmmm.. The only useless comment is the one about the default constructor, as it is obvious anyway. The rest of the comments seem sensible to me and I wouldn't edit them out. If I don't like the original formatting, then I usually copy it to my local editor and do the changes there. If I feel that it is really hurts reading, then I edit them in, but this example I wouldn't see like that. – Devolus Jan 8 '14 at 6:47
5

It Happens

I think we've all kind of dealt with this issue or an issue like it before. It's usually newer users who haven't quite gotten the grasp that the people correcting them have the reputation they have because they've been around to understand the common practices of the site. Nevertheless, enough people will eventually tell them to stop doing something or do something that they haven't been doing. Eventually this user in particular will see enough of those awful "For better help next time, post an SSCCE" comments.

Don't Fight

The important thing is to not get in a "Rollback War". Those get messy but they have created methods to stop these.

The First Point

The point is, take the unnecessary garbage out of your code before you post. Yes, you'll have users who WILL wade through it to find your issue, but at the end of the day, you are getting free help for programming issues, comply with the suggestions of the community.

The Second Point

A man convinced against his will is of the same opinion still

It's addressed here for the community to debate on, but if that individual is unwilling to comply, there is little we can do except utilize the controls we have been given. Perhaps it's a flaggable offense, but we would need a mod to weigh in on it.

  • 6
    Personally, if he wants to drown me in unneeded code and comments, I'll just move on. – Lance Roberts Jan 8 '14 at 4:54
  • Exactly. "Ain't nobody got time for that" – SomeShinyObject Jan 8 '14 at 5:48
5

If you're going to SOLVE his PROBLEM do so in the SOLUTION area provided at the bottom of each post. This allows you to clean up the formatting, remove the comments, and allow others following along to see the poorly formatted (and therefore harboring potential ills in the comment blocks) and the cleanly formatted.

Additionally, where you see waste, some people see "stub for documentation" and "corporate policy" and "good practice". So don't diss on everyone else's coding style for not being yours. Mind you, I prefer the 1TBS and at my company we use a modified Allman. I don't go around berating them for how dumb it is to have extra braces and newlines everywhere, but then again I am rabid about

if(condition) { <----- use this effing brace
  singleThing();
} <----- use this effing brace 

when my coworkers prefer this style:

if(condition)
  singleThing();

Guess how many fights I and my coworkers get into about braces and 1TBS vs Allman?

If you guessed "0" you're right.

TLDR

Fix it in the answer block and quit being so whiny. We all have our preferences on how code should be presented.

  • 1
    Yeah, I preferred the second style as well, until it bit us in the ass recently at work. Hard. Yep, someone added a line of code, but didn't include the necessary braces, and the line of code always executed, outside of the condition. Caused a hard crash in a very expensive system. – Robert Harvey Jan 8 '14 at 5:12
  • Yeah. I don't bitch about it too hard but anytime I have to add something in a class like that, I just tuck in a bit of extra braces as I read through the code. If I'm not already editing the class, I leave it alone. – jcolebrand Jan 8 '14 at 5:15
  • Weird, the only time I ever came close to having a problem like this was back in the darks days using a Borland non-colour-coded IDE, with an unclosed /*. That took me ages to find... – Benjol Jan 8 '14 at 6:31
  • If like me, you really want to not have the "extra" braces the solution is to insist that un-braced ifs and whiles go on one line. If they won't fit on one line, use the braces. – dmckee Jan 8 '14 at 15:03
5

One important thing nobody seems to have pointed out is that there is a difference between 'too many comments in code' and 'too many comments in code in a question'.

It's implicit in your question (I think), but calling it out explicitly might have helped to avoid getting into a war of religion.

Taking it back to first principles:

  • What is the aim of Stack Overflow? Getting answers to my programming questions.
  • What is the best way to get an answer? Make my question as easy as possible to parse - for easy also read quick.

Robert is right that you can mentally parse out comments (if you want), but I suspect that some users (as Lance Roberts says) will see 'no effort' and move on.

In that respect, if your quote of the OP as saying "it's too much work" is accurate, I'd say let him stew. It's his question, let him do the work. If he can get an answer without, good for him.

TL;DR;

The comments can be relevant to the code, but not to the question (and vice versa). It's a judgement call which is the case. Cluttered code in questions may get less attention, but that's the OPs problem.


(PS: Attitude. You come across as wanting to correct this user, as opposed to wanting to help him. I also find addressing him/her in the first person directly in your question text mildly off-putting)

  • This touches indeed more what I wanted to address, I believe I didn't express that well enough in my post. I certainly didn't want to come across like that; it's why I explicitly added that this is meant for me in case I was wrong. It didn't occur to me it might be interpreted like that, I'll edit it to avoid misunderstandings. – Jeroen Vannevel Jan 8 '14 at 5:46
3

It's not our business to tell our users not to comment their code, and it's not meta's business to settle a debate over comments in code or get someone to change their code philosophy.

If they have excessive comments, the idea that they're "excessive" is a matter of your own opinion. Apparently they like to program that way, and that's fine. You should probably not try to convince other users to program the way you want to program.

If they have incorrect comments, that's a very informative part of their question and possibly even part of the problem - they might misunderstand their own code, or they might just be working on outdated information. You might want to point this out whilst you provide a valid answer to their question.

In this case, readability isn't really affected, so that's not an issue.

Not the answer you're looking for? Browse other questions tagged .