Why so little code comment in Discourse Codebase? (Github)

Development

AI-generated summary

The discussion revolves around the limited code comments in the Discourse codebase on Github. 1c7 is attempting to customize Discourse and finds the lack of comments challenging. zogstrip explains that comments often become outdated and useless over time. 1c7 suggests that a moderate number of comments would be helpful.

1c7 also requests that the Discourse core team write about the big picture view of the codebase, including topics such as the folder structure, differences between GlobalSetting and SiteSetting, and the core model of Discourse.

vinothkannans and pfaffman advise 1c7 to use plugins for customization, as they offer more flexibility and allow for future upgrades. 1c7 thanks them for the suggestion and 1c7 agrees to look into themes and plugins.

1

https://github.com/discourse/discourse

Background

I was trying to customize Discourse.
(deep customization, theme/plugin is not enough, not a simple facelift change(logo, color, image etc))

I git clone to my laptop and start reading the code.
(I am Ruby on Rails dev & newbie Ember.js dev)

Question

  1. Why there are so little code comment in codebase?
    (controller / model / view / etc, both Rails and Ember)

I get the phrase “good code itself is comment” (or something like that)
But why so little?

Thanks.

2

Because comments tend to rot and deprecate which makes them useless (and sometimes counter intuitive) over time.

3

Thanks for reply

But 1-4 line comment per-controller/view/template/etc seem like reasonable number.
not too much, not too little

:smile:

4

I hope you guys(Discourse core team) can write few post about the
big picture view on Discourse codebase..
(not like “why chose Ember.js” I already read that one. deeper than that)

like:

  1. Why this folder structure(Ruby on Rails & Ember.js put together)
    I guess if you guys make Discourse from scratch in 2018,
    would decide separated Rails&Ember into 2 repo?
    or different folder structure

  2. What’s the different between GlobalSetting & SiteSetting?

  3. What’s the core model of Discourse? (Users&Post&Topic)?

  4. why preload_script is needed? example <%= preload_script 'break_string' %>
    preload_script return

# ... some other code
<link rel='preload' href='#{path}' as='script'/>
<script src='#{path}'></script>".html_safe

so it’s for SEO or some other reason?

  1. and few other question I couldn’t recall right now
5

You can/should use plugin.

6

OK, I would read more into plugin.
Thanks for the suggestion Vinoth Kannan

7

Unless you have a team of full time programmers or want never to take advantage of future upgrades to discourse, you want a plugin. Those who have forked are all sorry.

Almost anything can be accomplished with a plugin.

8

Got it, Thanks!
we do want future upgrade, would look into Theme and Plugin.
Thanks for reply!