Javascript: Aesthetic and Readable

Kvothe

The Bloodness
Veteran
Joined
Jan 21, 2014
Messages
148
Reaction score
552
First Language
Brazil
Primarily Uses
N/A
I just copy and paste here my article at Medium.

Sample code that was used on this article: Github

Sometime ago (about 6 months) I started to develop on Javascript. With focus on the engine RPG Maker MV (and creation of stuffs to website), in which I enjoy to create things. So with the practice and my previous experience with Ruby and C#, I became confident on programmation.

But one thing that always hunt me is the design of the code. I don’t if is that because I’m a graphical designer or whatever, but I like to do codes with aesthetic aspect for me and other peoples. So I’ll show up for you, dear dude, my way to doing aesthetic and readable codes on Javascript.

Summary of my way to do:
• Use JSDoc for commentary section and description of methods.
• Create a introduction part on the begin of code.
• Create keys to localize parts of the code.

Introduction part: See below the picture with the sample.
Take note: I recommend to set a limit of characters based on the space line (=====================================)​



Location part: On this part you will set a commentary section to indicates how the reader will get into that specific part faster (part of the code).
Pay Attention: The ‘symbol name’ need to get setup on the part from specific code. See below a example.
Take note
: You can write some codes before this part, but I recommend to don’t write big codes, just small parts (as ‘import’ list, for example)




But why? Because when is structured and have a good aesthetic design, will improve your time to read and edit after some time. And most important, the other person that will read your code will have a orgasm (believe me)!

Give your feedback and share your way to do aesthetic and readable codes!
 
Last edited:

Jonforum

Veteran
Veteran
Joined
Mar 28, 2016
Messages
1,606
Reaction score
1,399
First Language
French
Primarily Uses
RMMV
personally my brain can easy recognize and associate color when am reading. You need a lot of plugin but this can help if you are a colored guy.


i also love sometime use #region . The eye can easily track a part of code.
upload_2018-3-31_11-13-57.png
 
Last edited:

nio kasgami

VampCat
Veteran
Joined
May 21, 2013
Messages
8,600
Reaction score
2,359
First Language
French
Primarily Uses
Honestly when I write code I learned with time to go with fewer line of comment simply adding the important informations.
Prettyness is nice but this clunker the code to much and distract me.

so I go with the classic way of js comment :
Code:
/**
 * This an generic comment
 *
 * @AnyUsefulTag
you learn with time that prettyness will just distract u lol...

and honestly Also learn to work with modularity wich mean separate files so u know where files are...it is can be so much annoying to have to search for an 10k line of code file for know what does a class.

and by itself an method/parameter/variable/class should tell by itself what it does just by the name of it.
 

Jonforum

Veteran
Veteran
Joined
Mar 28, 2016
Messages
1,606
Reaction score
1,399
First Language
French
Primarily Uses
RMMV
Honestly when I write code I learned with time to go with fewer line of comment simply adding the important informations.
Prettyness is nice but this clunker the code to much and distract me.

so I go with the classic way of js comment :
Code:
/**
 * This an generic comment
 *
 * @AnyUsefulTag
you learn with time that prettyness will just distract u lol...

and honestly Also learn to work with modularity wich mean separate files so u know where files are...it is can be so much annoying to have to search for an 10k line of code file for know what does a class.

and by itself an method/parameter/variable/class should tell by itself what it does just by the name of it.
the comments do not really distract me, contrary, I learned my lesson when your return back on a huge code, 3 months later!
The comments will save you hours of analysis.
Also if your project have multiple modules.
 

Clock Out

Veteran
Veteran
Joined
Jun 14, 2016
Messages
92
Reaction score
44
First Language
English
Primarily Uses
RMMV
Simpler is better but above all, comment blocks should be indented so they can be folded out of the way. I think folding also makes those horizontal bars less useful than people realize. One or more blank lines is good enough to separate sections.

Providing an index of symbols in a comment unnecessary when editors like VS Code can provide a list with Ctrl+Shift+O. Add a : if you want to sort symbols by type.
 

LTN Games

Veteran
Veteran
Joined
Jun 25, 2015
Messages
645
Reaction score
502
First Language
English
Primarily Uses
RMMV
Comment blocks should be simple and small unless it's an open source project, in which case, more documentation the better because you expect more than just one or two people to read the code. But obviously most comments should be clear and concise not a paragraph or two long lol.

My current way of doing it and I hope once I'm finished those who want to learn how to develop plugins, will adopt it. I still have some amount of work to accomplish before it's available though.

Anyways, the worst downfall for any plugin is the fact most use one large file to put all your code, unless you use a file concatenation script. This makes it harder to read and keep track of things. The brain will process individual files or modules much quicker and it helps you write your code in a easier to handle manner.

So my solution at the moment is to have individual files for each new and existing module or class.

upload_2018-4-3_12-11-10.png

Three main files required for each plugin will be Core.js, main.js and Parameters.js. main.js is more like an index file that exports all files in the folder and if required, allows you to better handler what is exported.

FeniXCore plugin has this in it's main.js

PHP:
import {Signals, VERSION} from './Core'
import { PluginStore } from './PluginStore'
export {Signals, VERSION, PluginStore}
export * from './PluginManager'
export * from './DataManager'
export * from './SceneManager'
export * from './SceneMap'
The core.js handles important tasks like registration of the plugin, registration of event emitters and a few other things. Mainly, this is where you start the plugin and retrieve all data for use in the entirety of it.
Because it will be an open source plugin, I comment the important elements of the plugin. Not to mention because this is a core plugin some code varies compared to other plugins.
PHP:
/**
 * The plugins Core file, which contains registration and export of important
 * members.
 *
 * @file Core
 *
 * @author       FeniXEngine Contributers
 * @copyright    2018 FeniX Engine
 * @license      {@link https://gitlab.com/FeniXEngineMV/plugins/blob/develop/LICENSE|MIT License}
 */
import { PluginStore } from './PluginStore'
import { Signals as _Signals } from 'fenix-tools'

/**
 * The version of FeniXCore
 * @memberof FeniX
*/
export const VERSION = '2.0.0'

PluginStore.register({
  name: 'Core',
  version: VERSION,
  author: 'FeniXEngine'
})

/**
 * For use with core modules, for easy access to the core plugin client API.
 * @private
 */
export const _Plugin = PluginStore.require('Core')

/**
 * A signal dispatcher, used for emitting signals when important game events
 * occur.
 * @memberof FeniX
 */
export const Signals = _Signals()
And last is Parameters.js, which is literally all parameters and structs for your plugin, I won't show that here, we all know what it looks like.

Other files are simple enough, I import the functions and variables I need for that file and I proceed to do normal coding. If I need to export it so I can use it in other files then I simply export it, that's the beauty of ES6 and a bundler like rollup.

PHP:
/**
 *
 * @file DataManager
 *
 * @author       FeniXEngine Contributers
 * @copyright    2018 FeniX Engine
 * @license      {@link https://gitlab.com/FeniXEngineMV/plugins/blob/develop/LICENSE|MIT License}
 */
import { _Plugin, Signals } from './Core'
import { loadEventComments } from 'fenix-tools'

//  Overwrite or add to DataManager .........
All my parameters are parsed and available to the _Plugin variable created in the Core.js, and I can import it into other files to use.

PHP:
export const _Plugin = PluginStore.require('Core') // Gives access to all of the current plugins information and data.

_Plugin.parameters // Returns all parameters found in Parameters.js already converted and parsed to appropriate types.
I can code so much faster as well as retain information longer during development because of this type of workflow. Most large comments don't distract me because most files are small enough and don't require much reading to get to the heart of the code.
 

Jonforum

Veteran
Veteran
Joined
Mar 28, 2016
Messages
1,606
Reaction score
1,399
First Language
French
Primarily Uses
RMMV
@LTN Games
it will be especially the general technician who will tend to comment all.
The more specialized coder does not care, as they are delving into their codes much more often than the generalist developer.

Example I must navigate between several mastery.
Software and specific language:
AffectEffect, AffectEffect Scripting
Photoshop, Photoshop Scripting
Spine, spine Atlas libs,
TexturePacker,
Sprite Illuminator
sound forge
Basic Language:
HTML,CSS,PHP,JS,NPM,PowerShell,...
Libs Language:
RMMV, PIXI + Modules, Excel, Wordpress ...
General Informatique:
Deep Windows, hardware software, draw and configure a tablet, general electronic ...

Save, if you're lucky enough to be amphetamine-fueled and neuro-stimulant, which Americans do legally through their doctor.

I rather advice to comment everywhere and as much as possible.
But it remains my opinions.

This is one of the reasons that in a professional studio, everyone specializes in one areas, which is more difficult to do if your are indiDev.

ps: i like how you split your code by module.
 
Last edited:

Users Who Are Viewing This Thread (Users: 0, Guests: 1)

Latest Threads

Latest Profile Posts

Cheerleaders are my favorite thing on Czech hockey. Too bad they're the only thing worth watching on it.
meet with Quon,
the goddess of Rakuen (circle mascot)
It turns out that if I set the collider to 0,0,0,0 before despawning an event.... QMovement will actually play nice with Galv Event Spawner! :LZSexcite:
So I cloned an event in MV today.
Just got two custom tracks for my game. Things are shaping up nicely. :)

Forum statistics

Threads
93,503
Messages
913,069
Members
123,038
Latest member
ohsh
Top