Closed theGaryLarson closed 1 year ago
hmmm the snapshot test for dashboard v2 is still failing. I made sure I synced up main. Will discuss more with @Komal914 and @lloydchang at our meeting.
Please contact @GuillermoFloresV if you have further questions about this. Thanks!
Hi @theGaryLarson. Thanks for taking the initiative on this!
While I agree that we can improve a new contributor's understanding of the codebase, I also think that this method is not the best way to approach it.
One thing that the repo does need to do is make things a lot more readable and easy to digest/understand for new contributors. However, writing good comments should not excuse existing bad (and hard-to-understand) code. The code should instead be rewritten to be able to be picked up by someone who is investigating it and trace through it with some ease when trying to contribute. This is something that the codebase is continuously doing (the best example of this is our dashboard page being rewritten a few times for better code readability/easier to digest).
Another area of improvement is increasing the amount of resources provided by the repo, however, this can be tricky as resources become outdated over time. Instead, I believe we can clearly state what tech stack, libraries, etc. we are using for contributors to be able to look at when they have questions regarding those.
These two suggestions would be greatly beneficial to the codebase as they cover code we (contributors & maintainers) write and the libraries that are used (A baseline knowledge of how NextJS, Prisma, Tailwind, etc works would eliminate a lot of the need for new contributors to need a large amount of the comments this PR introduces).
While I am not opposed to new comments coming in to be able to understand complex parts of the codebase, I believe they should only be used to explain a "why" not a "what", if others have a differing opinion I am more than happy to chat about what type of comment truly is needed. As just mentioned we hope to write code that does not leave you scratching your head as to what it is doing, but rather why we are doing things a certain way. (Difference being you understand the code, and instead are curious as to the execution of our logic)
While I agree with the spirit of the PR I do not believe that commenting to the extent the PR does is entirely necessary. There are other (IMO, better) ways to improve a new contributor's contribution experience. That being said, if writing lots of comments to explain our logic is truly needed, we can write about them either in a blog post or enable the wiki for the project inside of GitHub where we can write about this type of stuff without cluttering files with tons of comments.
Closing this PR for now. I agree with @GuillermoFloresV's comment. A better way to help newcomers would be to improve the documentation, create a code walkthrough blog post / video, or create more system diagrams.
Update index.md
)Starts on #391
I used Mintlify AI doc generation to aid new devs in better understanding the code base. I created this as a draft PR and only doing a couple files each PR to avoid complex merge conflicts.