I agree, it would be great to have more tutorials regarding the code.
I think the biggest barrier in having them is finding people who want to make them. Considering the number of Blender users is probably about 2 orders of magnitude more than the number of people interested in programming Blender, the target audience is already pretty small.
This means the motivation to make it must be either personal interest or money. Money is unlikely to be the motivation since I feel like the idea of this sort of thing would be that it is open and accessible. I feel that there just isn’t that many people who like making Blender programming tutorials.
That being said, sometime this year I am planning on starting live streaming and among the activities I plan to stream is Blender development. This isn’t quite a tutorial, but I guess there are a lot of things that could help build a useful and friendly developer community around Blender.
My problem is that I’m just learning to code period. I just thought it would be awesome to have a codebase that was loaded with examples, and that’s why I originally posted.
Well if you’re able and comfortable then I guess GitHub becomes much more of a viable option. Of course, if you’re thinking of doing web programming then it might make a lot of sense to just add the website-style explorer to the developer.blender.org website. Of course, Blender might not let you add exotic features though. I guess you’ll have to talk to them - Ton or whoever.
You sound like you’re interested in making the best tutorial tool possible(which would be awesome): the best software always have exotic but useful features. If that’s the case, and Blender just so happens to not be cool with you adding an explorer division with exotic features to there website then that would give you a very good reason to create your own web-based explorer or Desktop explorer(whichever is better?).
Another possiblity is just have the best of both worlds: you can have your own GitHub explorer AND Blender can host there own tutorial division. Maybe your explorer can sync with there’s.
Firstly, let me just note that it seems that anything that I could say to you, you probably will already have thought of it or I just might be wrong altogether.
The biggest factors to consider are probably, getting programmers interested in writing tutorials and getting Blender’s respect and partnership. Even if this project gets off the ground it needs to last, and without the lifeblood of Blender backing it, it will most likely die. If integration into developer.blender.org happened Blender would be more likely to further invest. Plus, developer.blender.org already has traffic, and the best way to draw a crowd is with another crowd.
Another consideration would be that Blender already has the wiki and developer.blender.org. There’s the possibility that another info resource might become a dangling booger that everyone sees but no one acknowledges.
If your still interested, I would like to give some preliminary suggestions for such an explorer tool - after I think this through a little more. But, just know I can’t currently help with coding because I don’t yet know how to code very well. Real sad about that too.
Blender is almost 3 million lines of code, documenting it is a huge undertaking.
Bottom line is that unless you are willing to pay the price of reading the source which in most cases does not even have code comments , not to exclude the fact that some things are plain too weird to understand, not even the best tutorial in the world will be able to help you.
On other hand this also makes the possibility of forks very rare cause its so hard to modify undocumented code. Instead people are forced to rely on addons or small contributions. Thus limiting fragmentation for Blender source code and releases.
Agreed, but it would still be very helpful, especially to novice coders, to document as much as possible or at least whatever coders are willing to document. Also, note that I am under the impression that there are MANY coders that have made small (only small) contributions to Blender.
Actually, I would think that the right documentation software design could be used as a substitute for code embedded comments. Comment/documentation files could be mapped to and even synced with the code and git directory.
Nothing wrong with a challenge.
Maybe attempted forks should be viewed as a need for - some - form of a modular/plugin core design? The Blender design is already very heavily invested in enabling customization and python addons. So customization is natural to Blender. I suppose as long as strict but reasonable guidelines are given about how the plugins can be designed and there is a standard set of official plugins then a plugin architecture seems good for Blender - I guess. Btw, I’m not saying such a redesign is feasible.
Point is, I’m not so sure it’s - overall - in Blender’s best interest to have little documentation or be hard to modify.
Of course the Plugin system I have developed, I call them “Components” , are purely for my usage, not for public consumption but works well for my needs.
No it does not benefit Blender, basically because taking forked code and merging it back to the original repo is not that hard anyway. This is how Blender branches work. As long as you follow the source code which of course you will do to have access to latest cool features of Blender. Only problem is that it usually about to the contributors to bring their code to Blender devs standards. While forks follow their own standards so it will be up to Blender devs to modify the forked code to fit into the the main repository but that is a minor issue if the fork adds some major feature to Blender that Blender devs really want inside their repository.
Welcomes to the awesomeness of open source where we can help each other and have fun
Plus code reuse is the entire purpose of coding. All our tools. libraries and programming languages are built around this idea.
Also is kinda unfair to claim this, the whole purpose of this forum is to help people modify the source code. It’s not as if other open source project are overwhelmed with documentation. I even struggled to find good documentation for OpenGL for crying out loud. So no of course devs when people to take their code and making something out of it and frankly blender devs have many time went out of the way to help me with questions and problems.
So, are you implying that it would be relatively workable to convert the whole of Blender into a highly plugin architecture?
.
But didn’t you say earlier, "On other hand this also makes the possibility of forks very rare cause its so hard to modify undocumented code." ? You sounded as if you were saying that you thought the lack of comments and documentation in parts of Blender was a good thing because it prevents forks and fragmentation.
Also, I find it hard to believe that a highly plugin oriented architecture couldn’t(if done right) be considerably superior to Blender as is. Among other advantages, it would allow for end users to pick what specific modules they want to download and also what they want to dynamically run during any Blender session. For example, 3d artists, at the flip of a switch, could switch between two drastically different UI or (fill in blank) .Also, it would encourage creativity because module writers would know their module would probably be officially available : opensource coders like their work used and appreciated.
Claim what? I just think it would be really helpful to, at least, new inexperienced programmers to have a bunch of line by line tutorials/documentation(or more) available. I definitely appreciate all the resources that are already available to coders though.
Oh you want to make the entire Blender into plugins. It’s possible yes but there is no reason I can think of to go so extreme. It will be a lot of work though to break it down to plugins entirely.
I said it limits it, I did not say its good, nor did I imply that this is the intention. I mean that the reason why we dont see many forks is because source code is hard to change without extensive documentation. That’s all.
No idea how developers feel about this, there may be some practical problems that I am not aware of. Plus its extra work, to maintain both an Addons API and a Plugin API. It works well for me because I code only the part I need, so its super fast to develop it. It will be useless for someone else though unless he works on similar code.
So no a plugin system is not that much of a big deal. Sure changing the source code is hard but not that hard. Plus none messes with C unless he want to go deep and spend a lot of time with complex problems. Python is far better than that. So in the end Blender Python API would remain by far the most popular approach.
So no, even though I use a plugin system , I do not think it’s critical for Blender development. It’s just the way I like to work became I am an addon developer and will still be writing a lot of Python code for Blender.
Bottom line is that I enjoy our chat but in the end what matters is the actual work. We can debate this for years , unless we are willing to help in our way it matters very little. Blender is a community project, everyone is invited and it depends on the contributions , whether are code, bug reports, documentation and of course money.
I definitely agree with the title of this thread that documentation could go a lot way to motivate new developers but let’s face it, documentation is rare not just in open source projects but also closed source. Which is why YouTube has become the common place where people go to understand things.
On my part I will be documenting my code and providing a very minimalistic plugin system , of course provide extra documentation for Blender source code to a small extend. We can all help to make things easier in Blender we do not need to rely on others because Blender devs are already super busy with 2.8.
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 .
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.
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.
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 , 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.
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.
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.
