Tips for collaborating with a new project codebase

Working on a new project codebase can be both exciting and challenging. Whether you're an experienced developer or a newcomer, understanding how to navigate and contribute to an unfamiliar codebase is crucial for efficient and effective collaboration.

In this article, we provide tips to help you get started, what to do during the feature development process or fix, and how to conclude it on a high note using the Web Dev Path codebase as a reference.

Before you start coding

1. Familiarize yourself with the project structure

Understanding the project structure is your first step:

• Read the README: The README file usually contains essential information about the project, including setup instructions, dependencies, and a high-level overview of the codebase. It's the first document you should read to get an overall understanding of the project. Here's an example of our project's README file.

• Explore the file structure: Spend some time browsing through the directories and files to understand how the project is organized. Here's why it's important to look at these common folders:

  • src: This folder typically contains the application's source code. Understanding the organization of the source code helps you locate where to implement new features or find existing functionality.
  • components: This folder usually holds reusable UI components. Familiarizing yourself with these components can save time by allowing you to reuse existing ones instead of creating new ones from scratch.
  • utils: Utility functions and helpers are often found here. These functions can simplify your development process by providing pre-built functionalities for common tasks.
  • styles: This folder often contains styles and theming information. Understanding the styling conventions used in the project ensures that your additions remain consistent with the existing design.

2. Review documentation and comments

Documentation and code comments are invaluable resources:

• API documentation: If the project interacts with external APIs, read the API documentation to understand how data is fetched and handled. For example, in our project, you can look at the dev.to API documentation to understand how we fetch blog post data

• Code comments: Look for comments within the code. They often provide context and explanations for complex logic and decisions made by the original developers.

3. Set up the development environment

Ensure your development environment matches the project's requirements:

• Follow setup instructions: Carefully follow any setup instructions provided in the README or other documentation. For example, our project requires you to clone the repository and run yarn install to install dependencies.

• Install dependencies: Run the commands to install project dependencies, typically using package managers like npm or yarn. In our case, you might need to install specific versions of React, styled-components, and other libraries listed in the package.json file.

4. Understand the styling and component libraries

Consistency in styling and components is vital for maintaining a cohesive look and feel:

• Use existing components: Before creating new components, check if there are existing ones you can reuse. This helps maintain consistency and reduces redundant code that will not contribute to the project's maintenance.

• Refer to style guides: Adhere to any style guides or theming conventions used in the project. This might include using pre-defined or adhering to specific design patterns. For example, in our project, we must refer to the themeConfig.js for predefined styles and themes.

5. Study sample data and utilities

Projects often come with sample data and utility functions:

• Sample data: Look for sample data that can help you understand the structure and format of the data the project handles. For instance, check the blogContent.js file in the utils folder, such as blog post data.

• Utility functions: Familiarize yourself with utility functions that can simplify your work. These might include functions for data manipulation, API calls, or common UI operations. Explore the utils folder to see the helper functions you can leverage in your development process.

During the coding process

6. Communicate and collaborate

Effective communication is key to successful collaboration:

• Ask questions: Don't hesitate to ask questions if something is unclear. Engaging with your team can provide insights and help you avoid common pitfalls. If your questions require more detailed explanations, consider reaching out on Slack. PR conversation threads can become confusing, and a small meeting or a video can often be more efficient than a long comment thread.

• Request reviews early and use DRAFT Pull Requests: If you're unsure about your approach, request a review from a more experienced team member. Early feedback can save time and guide you in the right direction. When doing so, create a Draft PR. Draft PRs are meant for work in progress and are not ready for a full review. You can ask for feedback from one or two team members while keeping the PR as a draft. Only add all the remaining reviewers when your PR is ready for a complete review.

7. Follow best practices for code contribution

Adhering to best practices ensures your contributions are well-received:

• Write clean code: Follow coding standards and write clean, readable code. This means using meaningful variable names, writing modular code, and avoiding unnecessary complexity. Here’s an example of clean code:

// Bad Example
function a(arr) {
  let r = [];
  for (let i = 0; i < arr.length; i++) {
    r.push(arr[i] * 2);
  }
  return r;
}

// Good Example
function doubleArrayElements(elements) {
  return elements.map(element => element * 2);
}

• Commit regularly: Make frequent commits with clear, descriptive messages. This helps track your progress and makes it easier to review changes. For example :

git commit -m "Add function to double array elements"
git commit -m "Fix issue with array doubling logic"
git commit -m "Refactor doubleArrayElements function for readability"

• Test thoroughly: Ensure your code is well-tested. Write unit tests if applicable, and manually test your changes to confirm they work as expected. For front-end web features, it’s crucial to test in multiple browsers (e.g., Chrome, Firefox, Safari) and on different screen sizes (e.g., desktop, tablet, mobile) to ensure compatibility and responsiveness.

After finishing your PR

8. Learn from code reviews

Code reviews are an excellent opportunity for learning and growth:

• Embrace feedback: View feedback as a chance to improve your skills. Constructive criticism can help you become a better developer. It's important not to take any feedback personally. When a suggestion is unclear, reach out to the developer and try to understand their perspective.

• Review others' code: Participating in code reviews for others can give you insights into different coding styles and best practices. When reviewing others' work, try to provide links and examples whenever possible. This makes your feedback more actionable and easier to understand.

9. Document your changes

Proper documentation helps others understand your work:

• Update documentation: Ensure that any relevant documentation, including the README and CHANGELOG, is updated to reflect your changes.

• Write clear pull request (PR) descriptions: Provide a clear and concise description of your pull request, including what changes were made, why they were necessary, and how to test them. It's a good practice to have a PR template per project so each member has an itinerary to follow when submitting one.

Conclusion

Diving into a new codebase can feel overwhelming, but it becomes manageable and even enjoyable when you follow a methodical approach.

Start by understanding the project structure and reading through the documentation. Then, ensure your development environment is properly set up and familiarize yourself with the existing components and styles.

Effective communication and collaboration are key, so don't hesitate to ask questions and seek early feedback. Follow best practices for writing and testing your code and embrace the learning opportunities from code reviews. Proper documentation and clear PR descriptions help ensure the team understands and appreciates your contributions. Remember, the goal is always to work smarter, not harder.