"Programs must be written for people to read, and only incidentally for machines to execute"

– Hal Abelson

This is a somewhat long section, so here is a short-ish summary of why style matters:

• Programming is a collaborative activity, so it is important to know how to write code easily understandable by other humans.
• Many programmers will distrust and judge you if you routinely churn out unreadable and ugly code.
• Writing clean code reduces the chances that our code is buggy. This is especially important because software is an important part of our lives and is used to help keep people healthy, safeguard private information, support infrastructure... It's important we get this right.
• Pragmatically, many people in industry and in open source projects will conduct code reviews on your code and will and block changes that do not match their internal standards. The way we grade homework mimics this industry best practice.

Many people believe that when writing code, the only thing that matters is if your code is working or not. This is false – while it's important to get your code working, it is just as important to make sure your code is understandable to other people.

Programming is a highly collaborative activity – it's fairly common to have to work together with other people, sometimes even hundreds of them at a time! As a result, it's very important to write code that is easy to work with to allow others to integrate seamlessly with your work. Another benefit is that since clean code is easier to understand, you'll work much faster and introduce fewer bugs.

While you should not collaborate on homework assignments in CSE 142 and 143, it's still important to practice programming with good style – it's the core difference between whether or not a program is pleasant or impossible to work with.

For example, take the following piece of poorly written code:

         public void  f(int  n    ){
    for
   (int i=1;i<=n;i++){for(int j=i;j>0;--j)System.out.print("*")


  ;System.out.print("\n" )   ;
                             }
                             }

Can you tell what this code does? Not easily. Contrast that to the following code, which does the exact same thing, but is written to be much more readable:

public void printStaircase(int numSteps) {
    for (int i = 1; i <= numSteps; i++) {
        for (int j = 0; j <= i; j++) {
            System.out.print("*");
        }
        System.out.println();
    }
}

This is much more readable. Even if we don't understand a single line of code, we can infer from the very first line that this chunk of code will likely print a staircase, and roughly how the code works from the variable names and indentation.

This is obviously an extreme example, but it does demonstrate in a nutshell the importance of writing clean code.

Somewhat more broadly, focusing on writing clean code forces you to acquire an eye for detail. Programming, and writing correct programs requires careful attention, so it's better to acquire that habit sooner, rather then later.

After all, code is now a part of everyday life – we use code to control cars, control medical equipment, moderate our infrastructure, perform legal analysis, hold private data, and so forth. Many of you will go on to help create the software that ends up becoming an integral part of our life.

If that's the case, we have a responsibility to write as clean and well-designed code as possible to minimize the chances of bugs and accidents that might sneak in due to carelessness. As a result, the sooner you can get into the habit of caring about detail and correctness, the better.

And finally, purely from a pragmatic standpoint, many companies and open source projects will conduct code reviews on any changes you want to make to their codebase.

Some companies are less stringent about code reviews and will rubber-stamp whatever code you give them, and others are more stringent and will block changes if you have errors as small as a misplaced comma in a comment.

Either way, we want to prepare you to be successful in whatever environment you end up finding yourself in, and we do that by having our grading mirror the kind of code reviews you'll encounter in a professional setting.

If you approach style as a list of somewhat arbitrary rules to memorize, you will find it difficult to internalize what is and is not good style.

Instead, try and understand that all style guides, whether you follow ours or another organization's, are created primarily to help coders write more readable and less buggy code. If a rule exists, it's because without it, it's very likely your code will be messier and buggier.

More specifically, you'll find that all style rules ultimately stem from four fundamental principles regarding style: we want to write code that is readable, concise, modular, and efficient:

• Readable and consistent:

  Write code that is easily read and understood. This will make it easier for others to modify, extend, and use your code.

  Whenever you must make an arbitrary choice, consistently make the same choice to minimize confusion.

• Concise and lacks redundancy:

  Write code that contains no duplicate or copy-pasted code. This way, if someone needs to change something, you only need to change a single piece of your code, not every copied-and-pasted chunk.

• Well-organized and modular:

  Write code that is easily combined and reusable. Changing a single portion of your code should not cascade out and force you to rethink a large chunk of your codebase. Your code is modular and composes well, like legos or building blocks.

• Efficient:

  You write code that does not do extra work and does not consume unnecessary memory. The faster your code runs and the less resources it consumes, the better.

  As a note, we find that most students will initially have a poor understanding of what does and does not constitute "efficient code". Until we formally introduce the concept of efficiency and Big-O analysis in 143, I would not hugely worry about efficiency on your homework assignments. Doing what seems to be reasonable is likely to be the best approach.

We will elaborate on why exactly these four sections are important throughout this style guide, but for now, keep them in the back of your head. When you're not sure whether or not something is good style or not, just ask yourself: "how does doing X impact readability, concision, modularity, and/or efficiency?"

All this said, you will run into the occasional rule that seems to be largely arbitrary. For example, why do we name our variables using camelCase instead of using snake_case, like some other programming languages do?

This is a fair question, and in cases like these, the reasoning behind rules largely comes down to historical happenstance. We've tried to pick rules that are followed by the majority of the Java community, but there are always going to be slight differences from organization to organization.

For example, compare our style guide to Google's style guide vs Twitter's style guide . There are a lot of similarities, but the guides are not identical.

And of course, if we switch to a different programming language, the style guidelines are going to be even more different – for example, see the Python community style guide .

In the end, what's important is that you develop the discipline needed to be able to consistently conform to the standard of whatever convention you are required to follow, whatever they might be.