A suggestion to create an incentive to attract new novice code contributors

Preliminary concepts for the design of a codebase commentary manager and explorer

Abridged diagram version

Commentary Editor
A) This is like the locator bar in TortoiseGitMerge. The yellow reflects added code and the red reflects locations of comments.

B) The right side is an expandable comment, and the left is only a sympathetic expandable comment: the left file version does not have any actual comments linked with it. The comments are mapped to their counterpart code in codebase files and hopefully even synced with the code’s git repository and should, somehow, signify when the counterpart code has changed. Also, there can be two types of comments within the Commentary Editor: adjacent and nonadjacent(i.e. group comments). Note that formatted text, hyperlinks, images, etc can be put in the comment window. Also note that the yellow highlighted line of code is the newly added code for that commit version - I probably shouldn’t have included that - inside - the comment though because it’s confusing.

C) The right side is a collapsed comment, and the left is only a sympathetic collapsed comment.

D) These two things are file locations with differing commit hashes.

E) These two windows represent one of two modes: single window, and side by side comparison window. They function like a combination of Visual Studio’s text editor and TortoiseGitMerge side by side editor.

Codebase Explorer
F) These widgets function like they would in Visual Studio but with the added bonus of guiding students to commented code.

G) These are not functions (like you might expect). They are instances of named comments, and they are like hyperlinks to locations of the comments within the files.

H) This window is the Codebase Explorer and one of it’s purposes is to show a hierarchical tree view of a codebase.

I) These are highlighted new additions of code like what you’d find in TortoiseGitMerge .

TODO:
Overview Commentary Editor
Revision Graph Editor
?

=============================================

Unabridged text version

NOTE: Open this file with OpenOffice Apache.

CodeTutorialExplorer.xml (22.2 KB)

It seems what you are proposing is a huge documentation overhaul for Visual Studio. While this isn’t the place to discuss whether that idea is worthwhile, it definitely isn’t the place to discuss how to do it. It might or might not be possible, but it would be very low down on the priority list for developers of Blender.

If a similar outcome was desired with existing tools, I believe comments will show up as tool tips in header files in Visual Studio. For python, I’m not sure if there is automatic support for Pydoc in VS, but there’s a plugin for VS Code for it.

Code documentation, if you want IDE integration, has to be done in a standardised manner. Writing more documentation might be helpful but (controversial opinion warning) I’m not convinced that amateur code contributions will actually help Blender. That doesn’t mean documentation isn’t important, just that the motivation shouldn’t be getting more barely working code into Blender. I imagine the result of more code contributions from beginners might go something like this:

A beginner has an idea for a feature and heard that developing for Blender recently got easier because they added documentation. They spend a week trying to build their idea and do some basic tests in the expected use case of their feature. They submit a patch for it to be merged into Blender and it is rejected on the basis of inconsistent code formatting, lack of structure and use of suitable design patterns, and crashes Blender when doing something seemingly unrelated.

The beginner would feel like their contribution wasn’t valued and that the rejection was unreasonable because they spent a lot of time on it. They aren’t aware that an experienced developer could likely do the same task in a much better way in a couple of days.

Now this isn’t to say that the beginner should have done something different and the feature would have been merged, just that in order to make a positive contribution to a large code base, you need to understand what you’re doing. Aka. not a beginner. They just need to keep learning.

While I would very much love for VS to implement my design VS is just one possible avenue. As a matter of fact, if a large crowd of voters voted on this design suggestion on Microsoft’s suggestion forum then Microsoft would actually consider implementation. I used VS gui for the diagram simply because I like it not because it actually represents VS.

Within the “Relevant and Useful Ideas” section of my document I mention the possibility of this design being embraced by either TortoiseGit or some other open source code documentation software. However, I don’t know an enormous amount about coding so I am not sure about the details of such possibilities.

I would think you could garner the interest of this documentation/tutorial project from other open source contributors, and maybe you could get enough that this software concept could be realized? As a matter of fact, if enough people used it, and showed it to be useful - it could actually become a standard documentation tool by the masses.

I suppose maybe your right but where else should this be discussed? My preliminary proposal relates, in a big way, to Blender. My concepts could, in full, be implemented by Blender developers or in part. Even in part, say on developer.blender.org, would still be nice.

This design - does - allow for documentation to be done in a standardized manner. It’s possible for a single documentation project to be set apart as Blender’s official documentation project, and the project could/would have it’s very own repository under the hood. Every other documentation project could be separate from Blender’s.

Of course amateur contributions aren’t going to help much, but with REALLY good tutorials and documentation those amateurs will very quickly become experts, AND they will have a taste for Blender meat - yum!!!

I think you underestimate what it takes to become a good developer. Tutorials, documentation, explanations, no matter how good, will only get you 10% of the way there.

Creating a documentation standard is a huge undertaking. I’m not sure you quite grasp how big. Taking time away from Blender developers to get them to work on a mostly unrelated tool which will not benefit them but will likely result in the average patch submission being of lower quality is not in the best interests of developers.

There are already plenty of automated documentation tools which have integration with Visual Studio, VS code, and many other editors. I don’t think we need to create another one without a very good reason to do so. If there was a very good reason to do so, it wouldn’t be something just Blender would want/benefit from.

I estimate that it takes the study of architectural design, the study of at least one programming paradigm(let’s assume object oriented), study of refactoring methodology, study of object oriented design patterns, study of object oriented analysis and design, etc.

I’ve always stated that learning coding, in addition to documentation and tutorials, also requires a host of other things including time and practice.

I agree, but presumably this potential standard could organically create itself. If a superior documentation method( such as my concepts) was actually shown to tremendously improve coding proficiency then slowly it would grow in popularity and possibly eventually be accepted as a staple. This could mostly just happen organically.

Huh??? Teaching coders how to code Blender properly is going to keep them from coding Blender properly???

Ok. That’s one of the considerations that I pointed out in my “CodeTutorialExplorer.xml” document.

Assuming you are still interested in a code documentation venture, I am curious if you had any desire to contribute to some opensource documentation tool to improve it?

Also, were you still interested in, at least, developer.blender.org implementing a simple documentation division?

A few posts back, you seemed interested in a documentation tool. Have you now lost interest for some reason?

The people currently submitting patches have been ‘filtered’ by a high barrier-to-entry of Blender’s codebase. They are already proficient programmers. People who need good documentation in order to make a contribution are likely not going to make as good contributions as those who have on their own accord, learnt how it works.

I’m interested in improving documentation of Blender’s codebase. I’m not interested in attempting to create a new documentation standard. My initial understanding of what you were looking to achieve was way off what you’ve proposed.

I guess, but how strange to embrace a “high barrier-to-entry” by means of - willfully - letting the code go poorly documented. Aren’t there other better methods of high barrier-to-entry?

I originally just was hoping for something simple like a division on developer.blender.org that pairs tutorials with patches/commits and then you brought up the idea of something more:

"If we did end up going this route, GitHub pages might be a suitable place to host a website-style explorer. With a bit of front-end wizardry, we can decouple the data structure from the viewing method - I’m comfortable doing that. "

Well, it’s to bad you’re not interested in something bigger and better, BUT simple is good too. :grinning:

I don’t think that any developer is intentionally not documenting their code for this reason. Maybe there are, but I can’t think of any. Requiring 5 years professional experience? Seems awfully closed. Being super strict about performance regressions, crashes, code architecture and code style? Takes a lot of time from developers which could be working on something else.

A viewer of structured data is trivial. Really. If the structure was simple to parse, I could build a viewer in a few days. IDE integration of a new documentation standard is huge.

Bigger doesn’t always mean better. I’d say the best documentation tool is one which is easy to use for developers and helpful. It probably already exists.

Are you talking about something like Doxygen or Sphinx?

1 Like

@gsrb3d

Yes and no. My preliminary design concept is like Doxygen or Sphinx, at least so far as Doxygen and Sphinx are considered code documentation tools. My suggestions are only preliminary and so everything is pretty open-ended. In fact, my design could, possibly, be either integrated into another documentation program or another documentation program could be integrated into my design.

I was originally just hoping for line-by-line tutorials to be scattered throughout the Blender codebase. I, however, would REALLY like something as robust as what I’ve proposed though. I think that would really help new coders get up to par.

I will have to disagree with that one. Documentation will take you 99.99% there because the rest that will remain is to type a code you already understand 100%. This assumes complete understanding of the documentation. Of course that is the ideal maximum of documentation in coding that will never came close to achieving.

Usually documentation in coding it ranges from 0.1% to 1% and is mainly basic API reference docs and some relevant tutorials if one is lucky. Extensive documentation is basically a unicorn. Stuff of fairy tales. Documentation is in the end of the manifestation of knowledge in the form of documents.

Thus the next only viable option for a developer is to read the code and reconstruct his own documentation in his mind that will allow him to understand his problem and as return how to find a solution. So a coder becomes a Sherlock Holmes :smiley: , which is kinda fun.

Yeah good luck with that one, I remember making a small book on how to learn Python and took me forever.

https://archive.blender.org/wiki/index.php/User:Kilon/Python_book_of_magic/

Having to document 2 million lines of code would be an insane undertaking. Blender code will never be beginner friendly or friendly for any level of coder. That’s a fact that wont be changing any time soon , so get use to it. I would not recommend to anyone to work on Blender code unless he or she really wants to work on Blender code. I think its very important to have realistic expectations. What you suggesting does not come remotely close to realistic.

If one expects hacking Blender code to be an easy and fun experience, better make a 180 turn and head back to writing addons. I am still writing most of my code in Python and I do not think this will be changing any time soon.

2 Likes

I think we are basically saying the same thing in different ways. Inline documentation (the way it really is out ‘in the wild’) almost never gives you the whole picture. To have documentation explain everything you need, it would have to explain what OOP, Dependency Injection, interfaces etc etc are, and why they’re the correct thing to use in this part of the code. This just won’t happen. This sort of ‘documentation’ just becomes a tutorial/course. Which takes probably close to 10x the time to write compared to just writing the code.

exactly , I was referring to the general definition of documentation. I was not referring on the basics of the language , OOP etc but rather specific issues with the code, architecture design decisions, reasoning of implementation, gotchas of code usage etc. Generally documentation that is going way beyond your typical coder documentation which tends to stay on the very basics.

Sadly its that “extra” documentation that usually matters the most because reading the code make it relative apparent what the api is and the general usage, but once you want to go deeper in the rabbit hole then its when you need to bring in the big guns , your debugging/investigation skills and immense patience.

1 Like