#ProjectStruggles #CodingComplexity #CodeOrganizationTips
Hey there fellow coders! 👋 Have you ever found yourself in a situation where your project has become so big and complex that you’re starting to forget what certain parts of your code do? If so, you’re definitely not alone. Managing a large and complex project can be a daunting task, but fear not, I’m here to share some tips on how to effectively manage a complex project and keep your sanity intact. Let’s dive into some strategies for handling the struggle of keeping track of functions and variables, organizing your code, and the benefits of commenting.
Functions and Variables Management
When your codebase grows, the number of functions and variables can quickly become overwhelming. Here are some tips for managing them effectively:
1. Utilize meaningful names: It’s crucial to use descriptive and meaningful names for your functions and variables. This will make it easier for you to understand their purpose and usage when you revisit the code in the future.
2. Keep a reference document: Consider creating a reference document where you can list and briefly describe the purpose of each function and variable. This can serve as a quick lookup resource when you find yourself getting lost in the code.
3. Group related functions and variables: Organize functions and variables together based on their related functionality. This can help you quickly locate and understand the context of specific code sections.
Code Organization Strategies
As your project expands, maintaining code organization becomes increasingly important. Here’s how you can effectively organize your codebase:
1. Modularize your code: Break down large code files into smaller, more manageable modules. This can make it easier to navigate and maintain different parts of your project.
2. Use meaningful folder structure: Create a logical folder structure for your project that reflects its functional and modular organization. This can help you quickly locate specific pieces of code.
3. Apply consistent coding standards: Establish and adhere to consistent coding standards across your project. Consistency in coding style and organization can make it easier for you and your team to understand and maintain the codebase.
Leveraging Code Comments
Commenting your code can be immensely helpful, especially in a complex project. Here are some tips for effective code commenting:
1. Comment with purpose: Use comments to explain the intention behind complex or critical code segments. This can provide valuable context for understanding how specific parts of the code work.
2. Update and maintain comments: Don’t let your code comments become outdated or irrelevant. Make it a habit to update and maintain your comments as the code evolves.
3. Leverage inline documentation: Consider using inline documentation tools, such as JSDoc for JavaScript or Sphinx for Python, to automatically generate documentation from your code comments. This can be a time-efficient way to keep your codebase well-documented.
In conclusion, managing a complex project can be challenging, but with the right strategies and best practices, you can navigate through the complexity and maintain a clear understanding of your codebase. By effectively managing functions and variables, organizing your code, and leveraging code comments, you can tackle the challenges of a growing project with confidence and clarity. Happy coding, everyone! 🚀 #CodeManagement #ComplexProjectTips #CodeCommentsBenefits
Chill write it out on paper or a whiteboard
Create a readme.md file in the main project folder.
Use it to explain the overall architecture of your project and to outline where things are and what they do.
The bonus of this is, this is how larger collaborative projects work if you check some projects on GitHub.
Write it like a guide for someone else, so if you shared your project with someone they could get up and running with it.
Then, in subfolders which might contain related code, create more readme.md’s, to explain the purpose of the files in that folder.
Depending on the size of your project, you can link to the subfolders readme files from the main one, kind of like a table of contents.
Sometimes projects can grow so big it’s hard to keep track of things, documenting everything with readme’s is probably the best way and it means you’ll always have the documentation right there with your code if you close the project and come back to it at a later date.
Most important thing, document and organize your files into folders
Look into JSdoc/whatever equivalent for your lang
Files should be organized by the area they control – into folders. Keep like things together. It’s a good idea to refactor several times as your project grows. For me that often involves moving to different folders, renaming things for consistency etc. many problems are actually quite simple but we complicate them by not having a good naming system in place.
Also if you’re not using a strongly typed language, use the documentation to do so or try a strongly typed lang. They are self documenting in a way
Look up separation of concerns too. It happens differently for different paradigms but gives you a predefined project structure. For example, procedural/functional code will have actions and state separated completely. OOP is more about encapsulating state and actions into the correct area.
Also look up directional data flow. It’s much easier to follow code that takes on a tree structure, than a graph type structure with data and signals going in all directions. React is a good example of this tree structure – you can always follow where a component is called and where the original state comes from. A common criticism of OOP is that data can often go in any direction so it becomes hard to follow. Not that there aren’t ways to fix it, but it’s easy to misuse.
Finally, this is an art that comes with practice. Identify what’s difficult to follow in your current project and keep it in mind for next time.
And document! A sentence about what your function does and why it’s there is so helpful when you come back after a few months off.
I’d consider making an Entity Relationship Diagram, and Class Diagram to build a visual overview. For me it really helps to keep track of all the complexity.
Congratulations on this exciting new chapter of your journey!
If your language supports classes, you can probably mediate much of the complexity by applying inheritance and polymorphism more than you currently are. Part of the trick is not having to think about *how* some module accomplishes some task. If its behaviour is nicely encapsulated behind an interface with a sensible name (and please note I mean “interface” in the most general sense – not the Java/C# type or a networked API) it will become easier to reason about.
If your language does not support OOP (or not very well) my only advice would be to rewrite in a different language, but hopefully someone else will have more useful advice in that case!
Just in case you’re not doing this already … write comments for each line/block of code.
Your time has come to learn how to write automated “unit tests”.
These will help prevent future code changes from breaking the rest of the code. Plus each test gives you an example of how your functions are called and what their result is.
I agree with the other answers I’ve seen, with just one exception:
Rule #1 is TRUST YOURSELF!
* Popular IDEs including Visual Studio and PyCharm have spoiled programmers to utter ruin. IntelliSense is useful for newbies, and in cases where your project gets so big that you forget what you declared variables for and what far-flung functions do, but it encourages you to fire-and-forget while writing code. Then a release or an update gets pushed with bugs or performance drags, and you want to switch to a text editor that does a better job of syntax highlighting or code folding or whatever, but doesn’t have IntelliSense… and suddenly you have major issues because you don’t get handy popup or tooltip reminders of what does what and which parameters are of what data type.
* Don’t worry about breaking your code up into multiple files unless each file contains a separate Object aka Class or Struct Definition, or unless one file contains Global variables and functions while others are separately scoped. Many languages offer you absolutely no means of doing this anyway, as there is no #include statement available.
* If you broke your project into multiple files for a good reason, don’t be afraid to use some eldritch file-naming convention! I like to use hexadecimal numbering, such as 0x00.FirstCodeFile.ext and 0x01.NextCodeFile.ext and so forth, representing the cascade of dependencies. You can get as pedantic as you like with this, for example: 0x00.FirstCode.ext, 0x01.NextCode.ext, 0x01.0x00.NextSubCode.ext, 0x02.NextCode.ext
* Don’t worry about keeping track of ALL the moving parts of your project. Write just enough commentation so YOU will understand, in a second of glancing at a function or variable definition, what that thing does. Then when you need to write code which consumes or manipulates a Class or Global, it’s quick and easy to review and move forward.
* Use explicit variable-naming. Don’t try to be a code ninja with variable names just 1 or 3 characters long — use something that’s easy to recognize, and let it be as long as the compiler allows, such as: vartype_varpurpose
If I sit here thinking, long enough, I could keep writing forever. I’m sure most who read this will have at least a hundred similar tips that make better sense to themselves, and might make better sense to the OP too!
GOOD. YOU’RE LEARNING.
We all learn by production trauma. congratulate yourself for being a step forward in your learning
This is when good naming of objects, functions, and variables starts to really pay off. If you do it right, you don’t -have- to remember exactly what everything does. Abstraction is about ignoring the implementation details unless you’ve got a reason to dig in.
Also if you’ve done a good job of descriptive naming and keeping side effects to a bare minimum, it’ll be easy to re-learn what everything does when you need to.
The most exciting part in a big project is after you start documenting and whiteboarding and unit testing, when even that won’t be enough and you start reading through chunks of it wondering what idiot you borrowed that bit of code from. Thus enters the never ending refactoring process, whereby you rewrite the entirety of your program because the last idiot working on the code (as in you) did it incorrectly. Then you repeat this forever in a sisyphean nightterror.
I’d say it’s time to look into architecture, so those smaller files are easy to find too.
I’ve found UseCases [https://www.plainionist.net/Implementing-Clean-Architecture-UseCases/](https://www.plainionist.net/Implementing-Clean-Architecture-UseCases/) to be awesome [https://medium.com/thedevproject/clean-architecture-a-basic-example-of-folders-organization-aab07f9eea68](https://medium.com/thedevproject/clean-architecture-a-basic-example-of-folders-organization-aab07f9eea68).
You can use some well known ones, or make up your own, but in any case make sure to use an automated tool to keep it consequent like https://qossmic.github.io/deptrac/concepts/
Am I the only one curious to see the repo. U keeping it dry? In sub folders and all that? I feel like it must be a real mess for u to get lost like that
Being *way* more explicit with my function and variable names helped me a lot
Clearly name things, always comment, extensively if need be with a pseudo code example included, functions should only do one thing and remember inside every large program is a small program struggling to get out.
Have you considered breaking it down into individual packages/dependencies? You could break it down into individual self contained pieces and then have the main project put these pieces together. You might want to look up dependency inversion and dependency injection. You should also try automated unit testing and having your program broken down into modules like this will make it much easier.
Can you describe how you actually organize your code? From what I read I imagine you have lots of functions, variables and files.
It sounds like you are learning why people use modules.
A module is a chunk of code that does a defined thing or things. It has an explicit api that is how other modules use it. It’s like a library, except that it’s quite common for it never to be reused outside your project.
If (for example) you were to take all the bits that deal with cached data for a specific type of data and stick it in source code files in their own directory, then that’s a module. Then you make sure that all the calls into that module use an api that you’ve defined.
At that point, you don’t have to worry about that module when debugging something else.
To make even more sure you don’t have to worry about that code ever again, you write unit tests for all the api calls. Now you have tests which prove it’s working, and if you (or someone else) makes a change to it that breaks its behaviour, you will know about it.
Now you have a chunk of code that is “known working” with a defined interface, and you don’t need to worry about it any more.
Rinse and repeat.
Thus refactoring will take a long time. But it’ll still be quicker than debugging spaghetti code time after time.
what is the size of the project, for the starter? is it a one-man show? what’s the language?
Documentation, automated testing, example code, diagrams, tutorials, a project plan.
Projects must be designed to be completely forgotten and picked up again.
1 install Doxygen. 2 use it.
Doxygen would be a great third party tool to add to your work flow. It’ll create documentation from your own comments that you may always refer back to.