13 answers
Mike
Student
New Marlborough, MA
2
Questions
Asked
878 views
Is there any particular way that code should be formatted?
I look at my code sometimes and see that I do things pretty messily, and although I leave notes sometimes I look at the lines I have and dislike the way that they're arranged. Is there a specific way that code "should" be made to look like or is it okay just to leave notes if it works regardless? #computer-science #programming #tech
Login to comment
13 answers
James Ferguson
Product Management
16
Answers
San Francisco, California
Updated
James’s Answer
Don't focus on the styling - there are tools that can do that for you.
What you need to focus on is the structure and the organization of the code. Does it align with what you are trying to do? Is it obvious for others what the function of each component is. The reality of today's world is that you are almost never writing code for yourself, for only you to read. You need to write code that someone else can look at in 6 months, a year, 5 years and have *them* understand what the code does and why.
Understanding the algorithms and design patterns and writing what is essentially self-documenting code are key skills to making your code last.
What you need to focus on is the structure and the organization of the code. Does it align with what you are trying to do? Is it obvious for others what the function of each component is. The reality of today's world is that you are almost never writing code for yourself, for only you to read. You need to write code that someone else can look at in 6 months, a year, 5 years and have *them* understand what the code does and why.
Understanding the algorithms and design patterns and writing what is essentially self-documenting code are key skills to making your code last.
Dhairya Dalal
AI Research Scientist @ Posh Technologies
104
Answers
Boston, Massachusetts
Updated
Dhairya’s Answer
Yes! Learning to write clean, organized, and well-documented code is really important. If you decide to join a software company and are contributing to a large code base, you'll be expected to write clean and self-documenting code. Its useful for both your colleagues to be able to understand what your code does and to you when you come back to later in time and no longer have the context in the head. Also good coding practices will help you ace your interviews as it also will reflect well in coding interviews and clarity of thought. Even if you decide to do research, good coding habits will ensure reproducible research and help save time with with good organization.
Each language has different conventions that are worth looking into. As mentioned earlier, PEP8 is pretty standard for Python. Other language will have different conventions that you can look up. If you're using an IDE, you should be able to install a linter that will give you clues as to how to format your code. Its a good habit to also self document your code. For functions include a docstring and for complex logic leave comments to clarify your logic. Some folks like to have code fit within 80 chars margin (based on the width of the IBM punchcards). Honestly, that feels outdated as most standard monitors are wider and 120s is becoming more of a norm. Having a hard right margin ensures your code fits on a screen and can be read without needing to scroll right. Most developers also will have multiple code screens up side by side and so its nice to be able to view the full code without additional right scrolls.
There is a lot of materials out there for writing good software. Hers's a few resources to get you started:
Summary of Clean Code: https://gist.github.com/wojteklu/73c6914cc446146b8b533c0988cf8d29
Guide to Variable Names: https://dev.to/danialmalik/a-beginner-s-guide-to-clean-code-part1-naming-conventions-139l
Each language has different conventions that are worth looking into. As mentioned earlier, PEP8 is pretty standard for Python. Other language will have different conventions that you can look up. If you're using an IDE, you should be able to install a linter that will give you clues as to how to format your code. Its a good habit to also self document your code. For functions include a docstring and for complex logic leave comments to clarify your logic. Some folks like to have code fit within 80 chars margin (based on the width of the IBM punchcards). Honestly, that feels outdated as most standard monitors are wider and 120s is becoming more of a norm. Having a hard right margin ensures your code fits on a screen and can be read without needing to scroll right. Most developers also will have multiple code screens up side by side and so its nice to be able to view the full code without additional right scrolls.
There is a lot of materials out there for writing good software. Hers's a few resources to get you started:
Summary of Clean Code: https://gist.github.com/wojteklu/73c6914cc446146b8b533c0988cf8d29
Guide to Variable Names: https://dev.to/danialmalik/a-beginner-s-guide-to-clean-code-part1-naming-conventions-139l
Phil Nguyen
Senior Software Engineer
8
Answers
Portland, Oregon
Updated
Phil’s Answer
Different coding languages have different syntax, style guide, and formatting rules. Java, for instance - rules can be found here: https://google.github.io/styleguide/javaguide.html
I would say that it is more important to think about the future and whoever will be responsible for adopting the code you've written. The code should be documented, tested and fairly easily to understand for a new person on your team with a reasonable amount of experience already (for that role).
Everyone's writing/coding style will be different and these style guides and rules help to alleviate that. Make your code obvious and less complex - it sounds a little counter-intuitive but I much rather have simpler code than insanely efficient code written with multiple layers of abstraction.
I would say that it is more important to think about the future and whoever will be responsible for adopting the code you've written. The code should be documented, tested and fairly easily to understand for a new person on your team with a reasonable amount of experience already (for that role).
Everyone's writing/coding style will be different and these style guides and rules help to alleviate that. Make your code obvious and less complex - it sounds a little counter-intuitive but I much rather have simpler code than insanely efficient code written with multiple layers of abstraction.
Simeon Snow
Risk Assurance
1790
Answers
Houston, Texas
Updated
Simeon’s Answer
I don't think code "should" look a certain way as long as it is clean and easy to edit when you need to debug. You want some internal consistency and maybe to remember to add in notes with things like "--" or "//" before them, depending on the computer language you're using. You could try your hand at video game development. I'd recommend checking out Game Maker's Toolkit's community. You'll find people, especially on Discord, who would be excited to point you in the direction of free resources.
Pete Ezzo
Network Security Engineer
3
Answers
Cary, North Carolina
Updated
Pete’s Answer
It is very common to look at code you have written some time ago and not understand what it does. Formatting and arranging your code in consistent ways, and properly naming variables, functions, or methods, and organizing code along design patterns goes a long way to improving this. If you fail though - there is always refactoring.
Some languages (like Python) strongly recommend certain styles and layouts, like PEP-0008. Other languages are free-form but individual projects or employers will mandate a particular style. If your code is for your personal use and a temporary need it is likely fine to be messy. If you would like to work as a professional developer within a team setting how it looks will be much more important.
Some languages (like Python) strongly recommend certain styles and layouts, like PEP-0008. Other languages are free-form but individual projects or employers will mandate a particular style. If your code is for your personal use and a temporary need it is likely fine to be messy. If you would like to work as a professional developer within a team setting how it looks will be much more important.
Jay Hurst
Product Manager
55
Answers
San Francisco, California
Updated
Jay’s Answer
Mike,
Along with all of the other answers provided (which are all great) also keep in mind that the answer will depend on what team/company/project you are on.
As part of the working agreements on the development team, it is common to also agree on certain stylings in code formatting (tabs or spaces, indent amount, comment structure, variable naming, case preference, etc...). It is generally a good habit to get into to keep your code well organized and with some standards so that you can effectively work with other people on the team.
Best of Luck
Along with all of the other answers provided (which are all great) also keep in mind that the answer will depend on what team/company/project you are on.
As part of the working agreements on the development team, it is common to also agree on certain stylings in code formatting (tabs or spaces, indent amount, comment structure, variable naming, case preference, etc...). It is generally a good habit to get into to keep your code well organized and with some standards so that you can effectively work with other people on the team.
Best of Luck
Mickael Rosenberg
Software Engineer
261
Answers
Bellevue, Washington
Updated
Mickael’s Answer
Hi Mike,
Yes code should be formatted. The main reason is that cognitively, it is easier to read a code that always follows some patterns than randomly formatted code. If you read an entire file that follows a certain formatting and then come to a single function that breaks it, your brain will have a time too adapt to the new pattern and therefore this will be harder to read.
Are there general good practices?
I am tempted to say no, but there are.
Every body has their own preference in terms of "formatting" so the best good practice is a formatting that fits you.
But then, you barely code for yourself so the real first good practice is what your team does. And this is a compromise. Companies / teams will tend to have their best practices that you will have to follow. Some even invest in tools to parse and check the formatting of your code. All what other mention are things you will find (not necessarily enforced everywhere - really depends).
And because you are writing software for others as well as you, there are common practices like naming variables and functions a way they can be understood, comment part of your code that could be a little more obscure, and try not to have everything on a single line thinking that less lines means faster code. But I found that what one person finds neat, another may find it hard.
Yes code should be formatted. The main reason is that cognitively, it is easier to read a code that always follows some patterns than randomly formatted code. If you read an entire file that follows a certain formatting and then come to a single function that breaks it, your brain will have a time too adapt to the new pattern and therefore this will be harder to read.
Are there general good practices?
I am tempted to say no, but there are.
Every body has their own preference in terms of "formatting" so the best good practice is a formatting that fits you.
But then, you barely code for yourself so the real first good practice is what your team does. And this is a compromise. Companies / teams will tend to have their best practices that you will have to follow. Some even invest in tools to parse and check the formatting of your code. All what other mention are things you will find (not necessarily enforced everywhere - really depends).
And because you are writing software for others as well as you, there are common practices like naming variables and functions a way they can be understood, comment part of your code that could be a little more obscure, and try not to have everything on a single line thinking that less lines means faster code. But I found that what one person finds neat, another may find it hard.
Hanish Salindra Parthasarathy
Software Engineer Volunteer
83
Answers
United States
Updated
Hanish’s Answer
There’s no particular way your code should look because it doesn’t matter what your code looks like to the compiler. It’ll compile your code regardless of what it looks like. But in a professional and academic setting it’s suggested to use Indentation for your code to make it more readable. The benefit of this is that it makes it easier for you and others to read your code. This is definitely a great habit to cultivate. Hope this help! Good luck
Akanksha Singhal
Software Engineer
2
Answers
India
Updated
Akanksha’s Answer
If you use visual studio as IDE , do add some plugins For eg. https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode,
This would give you a fair idea on the code formatting expectations .
This would give you a fair idea on the code formatting expectations .
Mark Krause
Network Security
3
Answers
Potomac Falls, VA
Updated
Mark’s Answer
There are several things you can do to improve the formatting and readability of your code.
* Use plenty of white space to logically separate portions of your code.
* Keep line lengths to less than 80 characters.
* Comment your code.
* Use variable names that are self explanatory.
* Follow the coding and naming conventions for the language you are using, or the conventions established by the project, team, or employer.
* Logically decompose your code in to the appropriate modules / objects / classes in order to minimize the amount of code in an individual file.
* Reuse existing code (libraries, classes, etc.) whenever possible.
* Use plenty of white space to logically separate portions of your code.
* Keep line lengths to less than 80 characters.
* Comment your code.
* Use variable names that are self explanatory.
* Follow the coding and naming conventions for the language you are using, or the conventions established by the project, team, or employer.
* Logically decompose your code in to the appropriate modules / objects / classes in order to minimize the amount of code in an individual file.
* Reuse existing code (libraries, classes, etc.) whenever possible.
Byron McDaniel
4
Answers
Updated
Byron’s Answer
Some languages have a "preferred" look/format. Using consistent indentations and styles helps. Not only for the programmer who may have to go back after moving on to a new project and remember what they were doing, but for others who have to review and possible troubleshoot issues down the road. As a test engineer I have looked at a code written by a lot of others in order to determine what the intend was. For every problem there are numerous ways to solve. Consistent format and good documentation/commenting of what a particular block of code may be doing is helpful.
ashwani arora
Software Developer
1
Answer
Austin, Texas
Updated
ashwani’s Answer
There are different ways any code can be formatted.
One way u can always look for widely available templates, import those in your choice of IDE, and then IDE can then format your code by using simple shotcuts.
You can always make customization as per your needs.
One way u can always look for widely available templates, import those in your choice of IDE, and then IDE can then format your code by using simple shotcuts.
You can always make customization as per your needs.
Diarmait O'Reilly
Project Manager
9
Answers
Dublin, County Dublin
Updated
Diarmait’s Answer
Yes, its a shame to have to spend a lot of time trying to understand someone's code because of bad formatting or poor comments etc. particularly when working in a collaborative environment where multiple people may have to come back and work on "your" code.