It would probably be really helpful for the GSoC students to document their code

I think GSoC participants should be encouraged(but not at all required) to divide their code into logical categories(i.e. features) and produce .diff files for other coders to learn from. It seems like that would be very helpful and easy for them to do . I think that, if they wanted to, they could also, at least, lightly document their code. The fact that the logical categories would be distinguished within separate .diff files - would add clarity to their documentation.

It would be reeeally nice if they did that. No pressure though…

Personally I think making .diff files for specific parts of our projects is not a worthwhile use of time, especially because my project is not modular. I think most aren’t actually. That said, I’m trying to add comments and explanation where it’s helpful-- I think that’s a worthwhile goal.

2 Likes

I haven’t really checked what all the different projects are about, but I agree that some projects, like the Outliner project, don’t have a particularly bigger goal than to just add lots of semi related simple improvements or simple enhancements(albeit, very welcomed improvements and enhancements :slightly_smiling_face: ) . But surely there are some projects that do have a bigger and more focused goal?

It seems like dividing a focused goal oriented project into it’s logical components per .diff file, as opposed to one large commit, would make the code more understandable to newcomer coders. The fact that all the code within each .diff would have a common goal would add to understandability, and do so in a way that is superior to the diffs on https://developer.blender.org

I’m thinkin maybe this version of the students GSoC code could be kept separated(somewhere?) from their final version.

I doubt it would be difficult or take more than 30min - 2hrs to properly divide up and write particularly useful comments for a finished project.

All students have their own branch, you can see every incremental improvement that they have done, if you want a diff git can do that for you, no need to burden the students with that.

1 Like

I don’t think it’s a burden for someone who is familiar with a section of code to divide up their project into logical units and leave comments that would be useful for someone who is unfamliar. The students code should already be divided up within their mind anyway - because that’s how humans naturally make sense of everything. I’m just saying that it would be nice to put those divisible units on digital paper. I really don’t think that’s a big deal.

Also, you think that it would be just as easy for a new programmer to distinguish, on their own, the different GSoC branch components than to just have the student spell it out with a distinct .diff and a little extra commenting ? If so, I guess I’m just forced to have to take your word because I’m not in a position to justify an argument. I stiiill bet my suggestion would be better. Oh well…

I don’t know exactly where you’re coming from with your desire for .diff files. Once you’ve downloaded the code, it’s quite easy to look at a certain branch and look at specific commits in that branch. Developers already give their commits messages so it’s easy to tell what the goal was for a specific change. And when the projects are up for review the code will have to be in logical sections anyway.

I suggest you read about the various projects and the process before you suggest adding more work.

https://wiki.blender.org/wiki/GSoC/2019

The fact that the individual commits would be focused to one goal and that that goal would be outlined in the commit message - shows that my suggestion is already being used. So, I’m not suggesting something wildly different and exotic. I had assumed, and still do, that my suggestion was is likely just not being exercised on a more larger and useful scale - as it could be. But, since I haven’t yet made a copy of a GSoC branch I can’t say for sure one way or the other.

So, if it’s generally believed that it’s just as easy for a new programmer to clearly divide up and make sense of the differing project components using JUST the commit messages(as is) rather than having them spelled out in unique diffs - then I guess I’ll just take you at your word for now.

I just realized what you wrote here after a reread. What do you mean in this statement ? What will these “logical sections” look like ? Cause, it sounds like my suggestion is at least partly going to be realized as a natural part of GSoC. If so, cool.

You seem to be under the impression these students are more familiar with the code than you are, you have been around here for quite a few weeks/months already, effectively you have spent more time with the codebase than they have at this point in time.

Yeah, I’m under that impression. I have a brain fog disorder which causes everything to take 10, 20, 30+ times longer for me to accomplish than normal people :frowning:. Plus, I’m not a professional coder. Also, I was referring to the students divvying up their code at the end of GSoC.

I’m actually in the middle of coding a superior filtering sorting, and data manipulation system for the Outliner. If I should actually produce a finished product I’ll definitely be documenting my project in the way I’ve suggested - to help other newcomers.