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

Archive Blender Development
1

EDIT: I wrote a “Preliminary concepts for the design of a codebase commentary manager and explorer” post in post # 21 below.

It would probably be a REALLY helpful starter to most novice and intermediate programmers if sections of Blender’s code was explained (I mean something more than code comments).While, admittedly, each programmer needs to take the time to figure stuff out for themselves it would be a significant help and encouragement to have portions of the code base spelled out for them, and give them a really good start forward.

I would recommend explaining various functions, structs and enums line by line throughout the modules of Blender’s code base. I, admit, I don’t know the right quantity of functions, structs and enums that should be explained per module but there should at least be a few. I also think that patterns within Blender’s code base and architecture should be pointed out. Patterns and their recognition are a pillar towards learning.

In addition, it would probably be really helpful if coders would regularly explain their patches (at least the smaller patches), and so it would make sense to encourage developers to do this. In fact, it would make sense for Blender to have a page completely devoted to just this, and even maintained as it’s code contents are modified.

Again, I acknowledge this might seem like overkill, but I suspect that my suggestion could act as an incentive to attract new novice coders… Novice coders who will become professional coders…

I will also say that if this suggestion is taken seriously and acted upon then I would also recommend giving it clear exhibition, and making it easy and obvious for new programmers to find.

14 Likes
2

Consider this : a jigsaw picture puzzle that has solved pieces distributed throughout is going to be much easier to figure out then a completely blank and unsolved puzzle. As a puzzle becomes progressively solved the solved elements act as an accelerant by hinting toward the placement of other unsolved elements. Solved elements serve as clues toward figuring out unsolved elements.

1 Like
3

This is a very common problem because coders like to code and not to write documentation and design GUIs.

Luckily there is now a course on how to get started with blender development

The best way of course is to jump in and add documentation yourself , Blender is open source project afterall for this precise reason.

2 Likes
4

Yeah, I saw that a few days ago. I think it’s awesome. It doesn’t seem like it covers much code just yet though. In addition to that course and other learning methods and tools, I was thinking that a division of https://developer.blender.org could be created for the explaination of the differentials line by line (if the developer was so inclined). Who knows, maybe it’s expecting too much?

I’m not particularly invested in Blender code just yet, I’m just fartin’ around with it, but I will probably try to do just that if I learn it well or if I submit a patch.

EDIT: I was just thinking that maybe contributors think that the wiki documentation is for high quality and thorough tutorials only. If so, then this could be a deterrent to potential contributors. There needs to be a division available for the average shmuck to feel free to make his/her own tutorial at there own skill level.

5

There are wiki sites that do just that! See https://archive.blender.org/wiki/index.php/Dev:2.5/Source/Architecture/Operators/Tutorial/ for example. It’s a bit old but I think the principle still applies. There are other code wiki pages as well https://archive.blender.org/wiki/index.php/Dev:Source/Architecture/ and https://wiki.blender.org/wiki/Source for the newer wiki. Not sure how many pages need to be ported / updated to blender 2.8 though…

Meanwhile, I think looking at previous commits can be very helpful. For me, the best way to learn is by actually trying to change or implement small features form the dev’s todo lists. Because there are usually similar commits that you can learn from.

3 Likes
6

I have thought this would be a very beneficial addition to the Blender codebase. It seems logical that an easy to approach codebase would entice more contributions from the community, and I think this likely is the case. That being said, a codebase the size of Blender has many distinct areas, probably many with somewhat different and incompatible programming paradigms and patterns. I think the amount of documentation needed to bring a beginner up to the skill level needed to make a maintainable, performant patch with good usage of suitable programming paradigms and patterns is unachievable in reality.

Contributions which aren’t up to scratch could actually do more harm than good to Blender, so I understand the downside to having the codebase more ‘accessible’.

Again, I think this would be a fabulous contribution, and it would have certainly helped me get up and running in modifying Blender more quickly, but it seems like a pretty colossal task. Who knows, maybe with coordinated community input we could put something together.

1 Like
7

@izo

I’ve grazed through those links before. While there definitely seems to be some very helpful and essential information I didn’t see a lot of tutorials like the one you linked to. Also, I totally agree that the commits themselves are very very helpful too.

Actually, I was thinking that it would simply make a very nice addition to Blender development to have a huge number of mini (or even mega) tutorials like the Operator tutorial you posted. So, I agree that it’s not critically necessary. I figure that, with encouragement, contributors might give many tutorials and explanations of their many committed patches. I haven’t yet studied the wikis well enough to know just how helpful the wikis really are, but I still feel compelled to think that a tutorial division along side a commit would be an excellent addition to the https://developer.blender.org/. But again, I admit that I’m not experienced or even invested enough to make the call.

1 Like
8

@izo

You know, after a little thought I realize that potential code tutorial contributors of wiki might assume that the wiki is only for high quality tutorials. If they are then that could be a drawback for possible commit tutorials/explanations. There needs to be a division available for the average shmuck to feel free to make his/her own tutorial at there own skill level. Of course, there would then need to be some required signifiers clearly depicted alongside the tutorial to inform the public of the quality of the tutorial their learning from. That should solve the problem, I guess.

9

Well, the Blender codebase would only be part of the contributor’s learning sources. I doubt that they would limit themselves to just learning all the different aspects and paradigms of C/C++ through just Blender. Also, I was originally expecting that they might need to take a few - years - before they could be considered professional, and that sounds reasonable enough that my suggestion is still worthwhile - I think.

10

Certainly. I think having a running commentary of types regarding the codebase could be helpful, with useful learning resources, issues people faced and how they solved them, particular paradigms used in section of the code etc could be very beneficial.

What sort of format have you been considering for such a system? Honestly the best way to get something happening is just to start it yourself, I have found. If you’re interested, I think we could put something together which is open to contributions - either a parallel repository which just documents the codebase, or maybe, with permission from some of the BI devs, as you said, a section of developer.blender.org

1 Like
11

I’d have to put some thought in that before I posted anything. I’ve got a few suggestions though.

Yeah, that’s why I was hesitant to post. I don’t know that I’m in a position to contribute to a project right now. For one thing, I don’t think I’m smart enough or experienced enough. I’m hoping in the next few months things will change for me though. I feel sad about that too.

Hmmm. I think the platform and overseer for the code tutorial contribution database is actually pretty important for multiple reasons. One thing that should be considered about a git repository is that it doesn’t have the potential for all the advanced webpage features that could be developed specifically for this project.

I’m going to bed and I’ll comment more tomorrow.

12

That’s certainly a valid reason to be hesitant, but I don’t think anyone is expecting you to know everything. Not having time is a concern of mine too, I tend to over-commit to things. Imposter syndrome is a big part of development, though. It is likely that no-one knows the code as well as you might expect.

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. I guess it just comes down to what is most useful for users, easy to write and maintain, and accessible where the developers already are.

13

I made the exact suggestion on BlenderArtists, where I said that there should be more tutorials on the programming side of blender in order to expand it’s functionality since the rate of feature demand outstrips the ability for coders to provide any feature by a significant margin. People claimed that there were enough tutorials but I don’t believe this to be the case since even with general use blender I still learn new things thanks to the massive community driven tutorials despite considering myself to be fairly well versed in many aspects of the program. The responses ranged from indifference to hostility with regards to teaching people how to code but going deeper and deeper into other coding communities apparently this behavior is not exclusive to Blender.

At some point this needs to be addressed even if it is difficult. I know it will be difficult due to some people not being able to meet the standards for proper code and the fact that there would be more people needed to review the code as well. However, the philosophy behind “open source” loses a tiny bit of meaning if it become so restrictive that only the “elite” and insider coders understand how it works without making any attempts to reach out to the larger community through effective education of the workings of the software.

3 Likes
14

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.

5 Likes
15

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.:frowning_face:

16

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.

17

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.:wink:

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.

1 Like
18

Ooops too late I already done that :smiley:

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 :slight_smile:

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.

19

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.

20

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.

1 Like