The car cost items' terminology should be, for programmatic and variable naming purposes:
depreciation
roadTaxes
credit
fines
fuel
inspection
insurance
maintenance
parking
repairsImprovements
tolls
washing
For country codes, the 2-letter ISO country code must be used.
These standards should be used (for example, for variable names or object properties)
hour
week
month
twoMonths
trimester
semester
year
Coding | meaning |
---|---|
km | kilometer |
mi | mile |
mil(10km) | nordic mile |
Coding | meaning | note |
---|---|---|
L | metric litre | SI symbol and from IEEE abbreviation list |
gal(imp) | imperial gallon | gal is the standard abbreviation of gallon according to IEEE |
gal(US) | USA gallon | gal is the standard abbreviation of gallon according to IEEE |
Coding | meaning |
---|---|
L/100km | litres per 100 kilometres |
km/L | kilometre per litre |
mpg(imp) | miles per imperial gallon |
mpg(US) | miles per USA gallon |
L/mil(10km) | litres per nordic mile |
mil(10km)/L | nordic miles per litre |
km/gal(US) | kilometres per USA gallon |
The core function calculateCosts
which receives the user data from either the user input HTML form or the database, obeys the following structure:
{
countryCode,
currency,
depreciation: {
dateOfAcquisition: {
month,
year,
valueOfTheVehicle
},
dateOfUserInput: {
month,
year,
valueOfTheVehicle
}
},
insurance: {
amountPerPeriod,
period
},
credit: {
creditBool, // type boolean
yesCredit: {
borrowedAmount,
numberInstallments,
amountInstallment,
residualValue
}
},
inspection: {
averageInspectionCost,
numberOfInspections
},
roadTaxes: {
amountPerYear
},
//Form Part 2
fuel: {
typeOfCalculation, // type string: "money" or "distance"
currencyBased: {
amountPerPeriod,
period // type string: "month", "twoMonths", "trimester", "semester", "year"
},
distanceBased: {
considerCarToJob, // type boolean
carToJob: {
daysPerWeek,
distanceBetweenHomeAndJob,
distanceDuringWeekends,
distanceStandardUnit // type string: "km", "mi", "mil(10km)"
},
noCarToJob : {
distancePerPeriod,
period, // type string: "month", "twoMonths", "trimester", "semester", "year"
distanceStandardUnit // type string: "km", "mi", "mil(10km)"
},
fuelEfficiency,
fuelEfficiencyStandard, // type string, "L/100km", "mpg(US)", etc.
fuelPrice, // type number; currency per unit of volume standard. Ex: 1.4, that is 1.4 EUR / L
fuelPriceVolumeStandard // type string: 'L', 'gal(imp)', 'gal(US)'
}
},
maintenance: {
amountPerYear
},
repairsImprovements: {
amountPerYear
},
parking: {
amountPerMonth
},
tolls: {
calculationBasedOnDay, // type boolean
yesBasedOnDay: {
amountPerDay,
daysPerMonth
},
noBasedOnDay: {
amountPerPeriod,
period // type string: "month", "twoMonths", "trimester", "semester", "year"
}
},
fines: {
amountPerPeriod,
period // type string: "month", "twoMonths", "trimester", "semester", "year"
},
washing: {
amountPerPeriod,
period // type string: "month", "twoMonths", "trimester", "semester", "year"
},
//Form Part 3
publicTransports: {
numberOfPeopleInFamily,
monthlyPassCost,
taxi: {
costPerUnitDistance, // type number, ex: 0.5, that is [currency]/km
distanceStandardUnit // type string: "km", "mi", "mil(10km)"
}
},
income: {
incomePeriod, // type string: "month", "twoMonths", "trimester", "semester", "year"
year: {
amount
},
month: {
amountPerMonth,
monthsPerYear
},
week: {
amountPerWeek,
weeksPerYear
},
hour: {
amountPerHour,
hoursPerWeek,
weeksPerYear
}
},
workingTime: {
isActivated,
monthsPerYear,
hoursPerWeek
},
distance: {
considerCarToJob, // type boolean
carToJob: {
daysPerWeek,
distanceBetweenHomeAndJob,
distanceDuringWeekends,
distanceStandardUnit // type string: "km", "mi", "mil(10km)"
},
noCarToJob: {
distancePerPeriod,
period,
distanceStandardUnit // type string: "km", "mi", "mil(10km)"
}
},
timeSpentInDriving: {
carToJob: {
minutesBetweenHomeAndJob,
minutesDuringWeekend
},
noCarToJob: {
minutesPerDay,
daysPerMonth
}
}
}
The core function calculateCosts
returns an object with the following structure:
{
countryCode,
currency,
costs: {
totalPerYear,
totalEver,
perMonth: {
items: {
depreciation,
insurance,
credit,
inspection,
roadTaxes,
fuel,
maintenance,
repairsImprovements,
parking,
tolls,
fines,
washing
},
standingCosts,
runningCosts,
total
},
perUnitDistance: { //"km", "mile", etc.
runningCosts,
totalCosts
},
},
speeds: {
averageKineticSpeed,
averageConsumerSpeed //see for more details
// https://github.com/jfoclpf/autocosts/wiki/Kinetic-speed-vs.-Consumer-speed
},
publicTransports: {
calculated, //boolean whether the public transports info was calculated
toBeDisplayed: //boolean whether makes sense to display public transports
totalCostsOfStandardPublicTransports, //total costs of public transports in the city with monthly pass
furtherPublicTransports: { //further alternative public transports (train, outside residence city, etc.),
display, //boolean for further alternative public transports
totalCosts, //costs set to these further public transports
},
taxi: {
totalCosts, //usage of taxi as an alternative to car
costPerUnitDistance, //average price of taxi per unit distance
possibleDistanceDoneByTaxi, //km/miles/etc. that could be done by taxi with amount of this.taxiCosts
},
totalAlternativeCostsWhenUserHasNoCar, //total alternative costs by not having a car
ratios: {
ptCostsOverCarCosts, //public transports over car costs ratio
//ratio (costs of public transports)/(car costs) under which it shows public transports as alternative
ptCostsOverCarCostsThresholdForShowPt,
//ratio (costs of public transports)/(car costs) under which shows other alternatives, with further public transports (intercity trains for example)
ptCostsOverCarCostsThresholdForShowFurtherPt,
}
},
financialEffort: {
calculated, //boolean whether the public transports info was calculated
income: {
averagePerHour,
averagePerWeek,
averagePerMonth,
perYear,
},
workingTime: {
hoursPerWeek, //hours of work per week
weeksPerYear, //weeks of work per year
monthsPerYear, //months of work per year
hoursPerMonth, //average total working hours per month
hoursPerYear, //average total working hours per year
},
totalCarCostsPerYear, //total costs per year
workingHoursPerYearToAffordCar, //hours per year to afford the car
workingMonthsPerYearToAffordCar, //months per year to afford the car
daysForCarToBePaid, //number of days till the car is paid
financialEffortPercentage //percentage of income that car costs represent
},
drivingDistance: {
calculated, //boolean
perWeek, //average distance driven per month
perMonth, //total distance driven per month
perYear, //total distance driven per year
betweenHomeAndJob, //distance between home and job (one-way)
duringEachWeekend, //distance the user drives during weekend
},
timeSpentInDriving: {
calculated, //boolean
minutesBetweenHomeAndJob, //time (in minutes) driven between home and job
minutesInEachWeekend, //time (in minutes) driven during weekends
minutesPerWeek, //time (in minutes) driven per week
minutesPerDay, //time (in minutes) driven per day
daysPerMonth, //number of days driven per month
hoursPerMonth, //number of hours driven per month
hoursPerYear //number of hours driven per year
},
externalCosts: {
calculated, //boolean
handbookOfeExternalCostsURL,
pollution,
greenhouseGases,
noise,
fatalities,
congestion,
infrastructure,
totalPerMonth
},
details: {
numberOfDaysPerWeekUserDrivesToJob, //number of days per week, the user drives to job
ageOfCarInMonths,
credit: {
numberOfMonthlyInstalments,
totalPaidInInterests
}
},
standardUnits: {
speed, // km/h, mi/h, mil(10km)/h
distance, // km, mi, mil(10km)
fuelEfficiency, // L/100km, km/L, etc.
fuelPriceVolume // L, gal(imp) or gal(US)
}
}
-
If a certain javascript file has only one module, the filename shall be that module's name without the ending
Module
. For example, if a file has only the moduleautocosts.abcModule
, the file name shall beabc.js
. -
The directories structure tries to respect the directory structure for JavaScript/Node Projects.
Javscript modules should be used. This approach lets us decide what variables/methods we want to keep private (e.g. myGrades) and what variables/methods we want to expose by putting them in the return statement (e.g. average & failing).
The name of a module, except the main module autocosts
, should always end the wording Module
.
autocosts
|
|--- commons
|
|--- getFilesModule
|
|--- initializeModule
|
|--- userFormModule
|
|--- convertDataModule
|
|--- validateDataModule
|
|--- runResultsModule
|
|--- calculatorModule
| |--- conversionsModule
|
|--- showResultsModule
|--- chartsModule
|--- pdfModule
By the following pattern we also ensure all methods and variables are kept private until explicitly exposed.
File: myModuleA.js
:
root.myModuleA = (function (thisModule) {
//dependency
var myModuleB
function initialize() {
loadModuleDependencies()
}
function loadModuleDependencies(){
myModuleB = root.myModuleB
}
function A(){
...
}
function C(){
...
}
/* === Public methods to be returned ===*/
//own module, since it may have been defined erlier by children modules
thisModule.initialize = initialize
thisModule.C = C
return thisModule
})(root.myModuleA || {})
File: myModuleA1.js
:
root.myModuleA = root.myModuleA || {};
root.myModuleA.mySubmoduleA1 = (function() {
//dependency
var myModuleB
function initialize() {
loadModuleDependencies()
}
function loadModuleDependencies(){
myModuleB = root.myModuleB
}
function E(){
myModuleB.P()
...
}
function F(){
...
}
return {
initialize: initialize,
F: F
};
})()
With this structure it is possible to load all files on a fully asynchronous way, without concern on dependencies nor order of loading, that is:
$.when($.getScript('myModuleA.js'), $.getScript('myModuleA1.js')).then(function(){
root.myModuleA.initialize()
root.myModuleA.mySubmoduleA1.initialize()
//now all the methods are available
root.myModuleA.mySubmoduleA1.F()
root.myModuleA.C()
})
We follow Javascript on browsers variable: window.location
protocol://username:password@hostname:port/pathname?search#hash
-----------------------------href------------------------------
-----host----
----------- origin -------------
protocol
- protocol scheme of the URL, including the final ':'hostname
- domain nameport
- port numberpathname
- /pathnamesearch
- ?parametershash
- #fragment_identifierusername
- username specified before the domain namepassword
- password specified before the domain namehref
- the entire URLorigin
- protocol://hostname:porthost
- hostname:port
Variable names should be proceeded by url
, for example urlHref
for the whole url.
Check also our wiki home page.