Do I need to document every code?


#1

Hi,
I would like to know if I really need to document or comment every code to obtain Top Grade in Front End Certification


#2

The certifications aren’t graded, just pass or fail. My understanding is that you pass as long as you’ve passed the requisite algorithm challenges and fulfilled all user stories for the projects — nothing to do with documenting or commenting your code.

However, in the real world (including for future jobs), you’ll need to properly document your code, so it’s a good idea to get into the habit now. “Document” can mean different things: it could be anything from creating nicely formatted guides for using the API you created to simply writing so-called “self-documenting code”. At a minimum, make sure your code is reasonably easy to understand, give your variables and functions names that explain what they are for, and add a few comments where needed to explain why you’ve done things a certain way.


#3

There is no requirement to document your code nor are you graded - you either pass or fail - the quality is not a factor - just that it works. A job however will be different and you’ll need to heavily document your code (so if you leave the company, are fired, hit by a bus, etc; can understand your code).


#4

It doesn’t have to be that dramatic. It could be that a colleague is writing code that needs to integrate with yours, or it could even be reading your own code a couple of months later. Even the best programmers forget what functions they wrote are for and why they chose to write their code a certain way.


#5

My usual approach is “document the complex. document the cool.”

If you learned something interesting, write some comments to help lock it in your head.
If you did something with a lot of steps, write some comments to help the next person understand those steps.

Nothing too crazy since Devs should be able to read most of the code. :slight_smile:


#6

My approach is to write enough comments in the code so that if I were to return to it 12months from now, I could pickup where I left off. This approach has save my bacon many times.

The oldest production code I’ve had to come back to was 5years.

RockLobster7


#7

Heck, right now as a beginner doing these challenges, Ive come across a challenge that Im pretty sure is kinda similiar / built up on an earlier challenge so I go to look at it and I have no idea what Im looking at. Its cause of that I started being more descriptive when naming my variables and comment my code.

Im at a stage of my life / learning journey where Im surprised something I did actually worked and I end up having to go back over my code to find out why cause I was so sure there would be more steps involved or something :laughing: Making those little notes to myself by commenting my code helps a lot.


#8

This is good advice too. :slight_smile:

Just because you want efficient code, doesn’t mean it can’t be a little verbose.

var a; // tells you nothing about its contents

var usersList; // sounds a lot like it should be an array/object of users

var usersPersonalDataList; // still okay while adding a quick detail

var usersListThatContainsNameIdRomaticInterestsAndBloodType; 
// might be bit much ;P

#9

i agree with you @DaveC, i see no point in using cryptic variable names just because its [insert reason here]. I find using descriptive variable names makes for better supportable code.

Cheers
RockLobster7