GITAM Students: Writing Clean, Documented Code Comments in Your Internship Work

Write comments that explain why code does something, not what it does, and let clear names carry the rest. Add a short README and a few doc comments on public functions, and enforce style with a linter so your repository looks consistent. This guide gives you a rubric to score your own code before and after cleanup, plus a lint setup checklist you can finish in a single sitting.

Why code readability matters in a 14-day full stack internship

A short internship leaves little time for anyone to walk a reviewer through your work. The reviewer opens the repository, reads the README, skims a few files and forms an opinion. If the code explains itself, you spend your final days improving features. If it does not, you spend them answering questions.

The free two-week online internship from CareerSwami runs for 14 days, with a free offer letter and a free completion certificate after successful completion. Your repository is the tangible output of those days, so treat readability as part of the deliverable rather than polish added at the end.

What deserves a comment and what does not

Most beginner comments restate the code. Experienced reviewers value the opposite: comments that record decisions, constraints and surprises the code cannot show.

Comments worth writing

• The reason behind a non-obvious choice. For example, why you debounce a search input by 300 ms or why you store a value as a string.
• External constraints. An API that returns dates in an odd format, a rate limit, a browser quirk.
• Warnings. “Order matters here: auth middleware must run before the router.”
• TODO and FIXME notes with context. Say what is missing and why it was deferred.
• Doc comments on public functions, components and API routes. Inputs, outputs, errors.
• Regular expressions and formulas. One line saying what they match or compute.

Comments to delete

• Narration such as // increment i.
• Commented-out old code. Version control already remembers it.
• Apologies like // hacky but works with no explanation.
• Comments that contradict the code after an edit. A wrong comment is worse than none.
• Section banners that exist only to compensate for a file that is too long.

Naming conventions for a JavaScript and React stack

Good names remove the need for many comments. Pick one convention per category and keep it across the front end, back end and database layer.

Avoid single letters outside tiny loops, avoid abbreviations your teammate would not guess, and never name something temp unless it lives for two lines.

Short docs that travel with the code

Doc comments with JSDoc

JSDoc is plain comment syntax that most editors read to show hints while you type. Keep each block short: one sentence of purpose, then parameters, return value and thrown errors.

A README a reviewer can use in five minutes

1. One-paragraph summary of what the app does.
2. Tech stack as a short list.
3. Setup steps: clone, install, environment variables, run.
4. A sample .env.example file with no real secrets.
5. Main routes or screens, in a small table.
6. Known limitations and what you would build next.

Commit messages as documentation

Write messages in the form “Add validation to signup form” rather than “changes” or “final”. A readable history shows how you worked across the 14 days.

Worked example: cleaning up one Express route

This example is illustrative. It was written to demonstrate style and has not been run or tested.

Before:

// get data
app.get('/s', async (req, res) => {
  let d = await db.query('select * from s where c = ' + req.query.c);
  // loop
  let r = [];
  for (let i = 0; i < d.length; i++) {
    if (d[i].a == 1) r.push(d[i]);
  }
  res.send(r);
});

After:

/**
 * GET /students?course=CS101
 * Returns active students enrolled in the given course.
 * Responds 400 if the course query parameter is missing.
 */
app.get('/students', async (req, res) => {
  const courseCode = req.query.course;
  if (!courseCode) {
    return res.status(400).json({ error: 'course is required' });
  }

  // Parameterised query: never concatenate user input into SQL.
  const students = await db.query(
    'SELECT * FROM students WHERE course_code = ? AND is_active = 1',
    [courseCode]
  );

  res.json(students);
});

What changed: the route and variables have meaningful names, the pointless loop became a query condition, input is validated, and the only comments left explain a security decision and the route contract. Fewer comments, more information.

Before and after code-quality rubric

Score each row from 0 to 2 (0 = absent, 1 = partial, 2 = consistent) on your first working version and again after cleanup. The maximum is 20.

A rough reading: 0 to 8 needs a serious cleanup pass, 9 to 14 is workable, 15 to 20 is ready to show. Use the score to choose what to fix first, not as an official grade.

Lint and formatter setup checklist

A linter catches mistakes and a formatter ends style arguments. Set both up on day one so you never have to reformat the whole project later.

1. Confirm Node.js is installed and the project has a package.json.
2. Install ESLint as a dev dependency and generate a config with its init command.
3. Install Prettier as a dev dependency and add a small .prettierrc file.
4. Add the ESLint config that turns off rules clashing with Prettier.
5. Add lint and format scripts to package.json.
6. Install the ESLint and Prettier extensions in your editor and enable format on save.
7. Add node_modules, build folders and .env to .gitignore, and to the lint ignore list where relevant.
8. Run the lint script and fix errors before warnings.
9. Enable rules for unused variables and undefined variables at minimum.
10. Run lint and format before every commit, or add a pre-commit hook if you are comfortable with one.
11. Mention the commands in your README so a reviewer can repeat them.

Suggested 14-day plan for code quality

GITAM students: documenting internship code against university rules

The university-wide R24UG academic regulations (version 3.0) apply to the 2024-25 admitted batch of School of Technology UG programmes. They say at least one of Internship-1 or Internship-2 must be done in an industry, government body, NGO, PSU or MSME, approved by the HoD. They also set minimum durations of 3 weeks for Internship-1 and 12 weeks for Internship-2. A 14-day online internship is shorter than both, so do not assume it satisfies a required internship slot.

The regulations do allow credit transfer for SWAYAM or Coursera courses with prior approval, but they do not mention other online internships in the material available here. The 2023-24 B.Tech CSE syllabus lists a 1-credit Internship course (INTN2333) and mentions 8 hours a day for four weeks. That is an older excerpt, so check the current version for your batch.

What this means for you: treat this internship as practice and portfolio work, and keep your repository tidy because a faculty guide or HoD may want evidence of what you built. CareerSwami does not offer academic credit, so any academic use is a decision for your department.

Verification steps:

1. Open the current UG regulations at gitam.edu/academic-regulations and find the internship clause for your admission year.
2. Email your HoD asking in writing whether a 14-day online internship can count for anything, or only as extra learning.
3. Ask which documents your department expects for a recognised internship, such as an offer letter, report format or evaluation sheet.
4. Check the latest academic calendar for your semester to see when the summer internship window falls.
5. If you want to use a GitHub repository as evidence, ask your faculty guide whether code and README links are acceptable.

Frequently Asked Questions

How many comments should a file have?

There is no ideal count. Aim for a comment wherever a reader would otherwise ask “why?”, and nowhere else. A clean file may have only three comments and still be well documented.

Should I write comments in complete sentences?

Short, plain sentences are best. Skip slang and jokes, because a reviewer in another team may read your code months later. Keep the tense and tone consistent.

Is JSDoc necessary for a small project?

It is not mandatory, but doc comments on API routes and shared helpers take a minute each and make editor hints more useful. Prioritise public functions over internal ones.

Which naming style should I use for database columns?

Either snake_case or camelCase works. The key is consistency, and translating at one clear boundary if the database and JavaScript differ.

What do I do with old code I may need later?

Delete it and rely on Git. If you might want it, commit first with a clear message or create a branch. Commented-out blocks only add clutter.

Will ESLint fix my code automatically?

Partly. Many style issues can be auto-fixed, but logic problems, poor names and missing comments need your judgement. Run the lint script to see which category each issue falls into.

Can a good README replace code comments?

No, they serve different readers. The README explains how to run and use the project; comments explain why specific lines exist. A strong repository has both.

Will clean code get me placed or a particular grade?

Nothing here guarantees either. Clean code makes your work easier to evaluate, and it is a habit worth building regardless of outcome.

Related Full Stack Web Development guides

• Maharaja Surajmal Brij University Students: A Local Business Website Internship Project
• Mahindra University Students: Setting Up CI Checks for an Internship Repository
• HBNI Students: Research Lab Tools as a Full Stack Internship Project
• All Full Stack Web Development internship guides