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


(Cheng Zheng) #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.


(Régis Hanol) #2

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


(Cheng Zheng) #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:


(Cheng Zheng) #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

(Vinoth Kannan) #5

You can/should use plugin.


(Cheng Zheng) #6

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


(Jay Pfaffman) #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.


(Cheng Zheng) #8

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